chore(i18n): refresh pt-BR translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
867ee40f9d
commit
6bceda86d3
106
docs/pt-BR/ci.md
106
docs/pt-BR/ci.md
@ -2,13 +2,13 @@
|
||||
read_when:
|
||||
- Você precisa entender por que um job de CI foi ou não executado
|
||||
- Você está depurando verificações do GitHub Actions com falha
|
||||
summary: Grafo de jobs de CI, gates de escopo e equivalentes de comandos locais
|
||||
summary: Grafo de jobs de CI, gates por escopo e equivalentes de comandos locais
|
||||
title: Pipeline de CI
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T13:59:22Z"
|
||||
generated_at: "2026-04-23T14:55:04Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: c5a8ea0d8e428826169b0e6aced1caeb993106fe79904002125ace86b48cae1f
|
||||
source_hash: e9a03440ae28a15167fc08d9c66bb1fd719ddfa1517aaecb119c80f2ad826c0d
|
||||
source_path: ci.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -18,81 +18,80 @@ x-i18n:
|
||||
A CI é executada em cada push para `main` e em cada pull request. Ela usa escopo inteligente para pular jobs caros quando apenas áreas não relacionadas foram alteradas.
|
||||
|
||||
O QA Lab tem lanes de CI dedicadas fora do workflow principal com escopo inteligente. O
|
||||
workflow `Parity gate` é executado em alterações correspondentes de PR e em acionamento manual; ele
|
||||
faz build do runtime privado do QA e compara os pacotes agentic simulados GPT-5.4 e Opus 4.6.
|
||||
O workflow `QA-Lab - All Lanes` é executado nightly em `main` e em
|
||||
acionamento manual; ele distribui em paralelo o parity gate simulado, a lane Matrix ao vivo e a lane
|
||||
Telegram ao vivo como jobs paralelos. Os jobs ao vivo usam o ambiente `qa-live-shared`,
|
||||
workflow `Parity gate` é executado em alterações de PR correspondentes e por disparo manual; ele
|
||||
compila o runtime privado do QA e compara os pacotes agentic simulados GPT-5.4 e Opus 4.6.
|
||||
O workflow `QA-Lab - All Lanes` é executado todas as noites em `main` e por
|
||||
disparo manual; ele distribui o mock parity gate, a lane Matrix ao vivo e a lane Telegram ao vivo como jobs paralelos. Os jobs ao vivo usam o ambiente `qa-live-shared`,
|
||||
e a lane do Telegram usa leases do Convex. `OpenClaw Release
|
||||
Checks` também executa essas mesmas lanes do QA Lab antes da aprovação de release.
|
||||
Checks` também executa as mesmas lanes do QA Lab antes da aprovação da release.
|
||||
|
||||
## Visão geral dos jobs
|
||||
|
||||
| Job | Finalidade | Quando é executado |
|
||||
| Job | Objetivo | Quando é executado |
|
||||
| -------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------- |
|
||||
| `preflight` | Detectar alterações somente em docs, escopos alterados, extensões alteradas e montar o manifesto de CI | Sempre em pushes e PRs que não são draft |
|
||||
| `security-scm-fast` | Detecção de chave privada e auditoria de workflow via `zizmor` | Sempre em pushes e PRs que não são draft |
|
||||
| `security-dependency-audit` | Auditoria do lockfile de produção sem dependências contra avisos do npm | Sempre em pushes e PRs que não são draft |
|
||||
| `security-fast` | Agregador obrigatório para os jobs rápidos de segurança | Sempre em pushes e PRs que não são draft |
|
||||
| `build-artifacts` | Build de `dist/`, UI de controle, verificações de artefatos construídos e artefatos reutilizáveis para jobs downstream | Alterações relevantes para Node |
|
||||
| `checks-fast-core` | Lanes rápidas de correção em Linux, como verificações de plugins integrados/contratos de plugin/protocolo | Alterações relevantes para Node |
|
||||
| `checks-fast-contracts-channels` | Verificações fragmentadas de contratos de canal com um resultado agregado estável | Alterações relevantes para Node |
|
||||
| `checks-node-extensions` | Shards completos de teste de plugins integrados em toda a suíte de extensões | Alterações relevantes para Node |
|
||||
| `checks-node-core-test` | Shards de teste do core Node, excluindo lanes de canais, integrados, contratos e extensões | Alterações relevantes para Node |
|
||||
| `extension-fast` | Testes focados apenas nos plugins integrados alterados | Pull requests com alterações em extensões |
|
||||
| `preflight` | Detectar alterações apenas em docs, escopos alterados, extensões alteradas e compilar o manifesto de CI | Sempre em pushes e PRs que não são draft |
|
||||
| `security-scm-fast` | Detecção de chaves privadas e auditoria de workflow via `zizmor` | Sempre em pushes e PRs que não são draft |
|
||||
| `security-dependency-audit` | Auditoria do lockfile de produção sem dependências contra advisories do npm | Sempre em pushes e PRs que não são draft |
|
||||
| `security-fast` | Agregador obrigatório para os jobs rápidos de segurança | Sempre em pushes e PRs que não são draft |
|
||||
| `build-artifacts` | Compilar `dist/`, Control UI, verificações de artefatos compilados e artefatos reutilizáveis para downstream | Alterações relevantes para Node |
|
||||
| `checks-fast-core` | Lanes rápidas de corretude no Linux, como verificações de bundled/plugin-contract/protocol | Alterações relevantes para Node |
|
||||
| `checks-fast-contracts-channels` | Verificações fragmentadas de contratos de channel com um resultado agregado estável | Alterações relevantes para Node |
|
||||
| `checks-node-extensions` | Shards completos de testes de bundled-plugin em toda a suíte de extensões | Alterações relevantes para Node |
|
||||
| `checks-node-core-test` | Shards de testes do core Node, excluindo lanes de channel, bundled, contract e extension | Alterações relevantes para Node |
|
||||
| `extension-fast` | Testes focados apenas nos bundled plugins alterados | Pull requests com alterações em extensões |
|
||||
| `check` | Equivalente local principal fragmentado: tipos de prod, lint, guards, tipos de teste e smoke estrito | Alterações relevantes para Node |
|
||||
| `check-additional` | Arquitetura, limites, guards de superfície de extensão, limites de pacote e shards de gateway-watch | Alterações relevantes para Node |
|
||||
| `build-smoke` | Testes smoke da CLI construída e smoke de memória na inicialização | Alterações relevantes para Node |
|
||||
| `checks` | Verificador para testes de canal com artefatos construídos mais compatibilidade Node 22 apenas em push | Alterações relevantes para Node |
|
||||
| `check-docs` | Verificações de formatação, lint e links quebrados da documentação | Docs alteradas |
|
||||
| `skills-python` | Ruff + pytest para Skills baseadas em Python | Alterações relevantes para Skills em Python |
|
||||
| `checks-windows` | Lanes de teste específicas do Windows | Alterações relevantes para Windows |
|
||||
| `macos-node` | Lane de teste TypeScript no macOS usando os artefatos construídos compartilhados | Alterações relevantes para macOS |
|
||||
| `macos-swift` | Lint, build e testes Swift para o app macOS | Alterações relevantes para macOS |
|
||||
| `android` | Testes unitários Android para ambas as variantes mais um build de APK debug | Alterações relevantes para Android |
|
||||
| `check-additional` | Guards de arquitetura, limites, superfície de extensões, fronteira de pacote e shards de gateway-watch | Alterações relevantes para Node |
|
||||
| `build-smoke` | Testes smoke da CLI compilada e smoke de memória na inicialização | Alterações relevantes para Node |
|
||||
| `checks` | Verificador para testes de channel de artefatos compilados mais compatibilidade push-only com Node 22 | Alterações relevantes para Node |
|
||||
| `check-docs` | Formatação, lint e verificações de links quebrados da documentação | Docs alteradas |
|
||||
| `skills-python` | Ruff + pytest para Skills com backend em Python | Alterações relevantes para Skills em Python |
|
||||
| `checks-windows` | Lanes de teste específicas do Windows | Alterações relevantes para Windows |
|
||||
| `macos-node` | Lane de testes TypeScript no macOS usando os artefatos compilados compartilhados | Alterações relevantes para macOS |
|
||||
| `macos-swift` | Lint, build e testes em Swift para o app macOS | Alterações relevantes para macOS |
|
||||
| `android` | Testes unitários do Android para ambos os flavors mais um build de APK debug | Alterações relevantes para Android |
|
||||
|
||||
## Ordem de fail-fast
|
||||
## Ordem de falha rápida
|
||||
|
||||
Os jobs são ordenados para que verificações baratas falhem antes que as caras sejam executadas:
|
||||
Os jobs são ordenados para que verificações baratas falhem antes de as mais caras serem executadas:
|
||||
|
||||
1. `preflight` decide quais lanes existirão. A lógica `docs-scope` e `changed-scope` são etapas dentro desse job, não jobs independentes.
|
||||
2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` e `skills-python` falham rapidamente sem esperar pelos jobs mais pesados de artefatos e matriz de plataforma.
|
||||
3. `build-artifacts` se sobrepõe às lanes rápidas de Linux para que consumidores downstream possam começar assim que o build compartilhado estiver pronto.
|
||||
4. Depois disso, as lanes mais pesadas de plataforma e runtime se distribuem: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-extensions`, `checks-node-core-test`, `extension-fast` apenas para PR, `checks`, `checks-windows`, `macos-node`, `macos-swift` e `android`.
|
||||
1. `preflight` decide quais lanes existirão. A lógica `docs-scope` e `changed-scope` são steps dentro deste job, não jobs independentes.
|
||||
2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` e `skills-python` falham rapidamente sem esperar os jobs mais pesados de artefatos e matriz de plataforma.
|
||||
3. `build-artifacts` se sobrepõe às lanes rápidas de Linux para que os consumidores downstream possam começar assim que o build compartilhado estiver pronto.
|
||||
4. Depois disso, as lanes mais pesadas de plataforma e runtime são distribuídas: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-extensions`, `checks-node-core-test`, `extension-fast` apenas para PR, `checks`, `checks-windows`, `macos-node`, `macos-swift` e `android`.
|
||||
|
||||
A lógica de escopo fica em `scripts/ci-changed-scope.mjs` e é coberta por testes unitários em `src/scripts/ci-changed-scope.test.ts`.
|
||||
Edições no workflow de CI validam o grafo de CI Node mais lint de workflow, mas não forçam por si só builds nativos de Windows, Android ou macOS; essas lanes de plataforma continuam com escopo restrito a alterações no código-fonte da plataforma.
|
||||
As verificações Node do Windows têm escopo restrito a wrappers específicos de processo/caminho do Windows, auxiliares de runner npm/pnpm/UI, configuração do gerenciador de pacotes e superfícies do workflow de CI que executam essa lane; alterações não relacionadas em código-fonte, plugins, install-smoke e somente testes permanecem nas lanes Node de Linux para que não reservem um worker Windows de 16 vCPU para cobertura que já é exercitada pelos shards normais de teste.
|
||||
O workflow separado `install-smoke` reutiliza o mesmo script de escopo por meio do seu próprio job `preflight`. Ele calcula `run_install_smoke` a partir do sinal mais restrito de smoke alterado, então o smoke de Docker/instalação é executado para alterações relevantes de instalação, empacotamento, contêiner, produção de extensão integrada e nas superfícies do core de plugin/canal/Gateway/Plugin SDK que os jobs smoke de Docker exercitam. Edições somente de teste e somente de docs não reservam workers Docker. O smoke de pacote QR dele força a camada Docker de `pnpm install` a ser executada novamente enquanto preserva o cache do BuildKit pnpm store, então ainda exercita a instalação sem baixar novamente as dependências em cada execução. O e2e `gateway-network` reutiliza a imagem de runtime criada anteriormente no job, então adiciona cobertura real de WebSocket entre contêineres sem adicionar outro build Docker. O `test:docker:all` local faz prebuild de uma imagem compartilhada de teste ao vivo e uma imagem compartilhada de app construído de `scripts/e2e/Dockerfile`, depois executa em paralelo as lanes smoke live/E2E com `OPENCLAW_SKIP_DOCKER_BUILD=1`; ajuste o paralelismo padrão de 4 com `OPENCLAW_DOCKER_ALL_PARALLELISM`. O agregador local para de agendar novas lanes no pool após a primeira falha por padrão, e cada lane tem um timeout de 120 minutos que pode ser substituído com `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`. Lanes sensíveis à inicialização ou ao provedor são executadas exclusivamente após o pool paralelo. O workflow reutilizável live/E2E espelha o padrão de imagem compartilhada ao fazer build e push de uma imagem Docker E2E GHCR com tag SHA antes da matriz Docker, depois executa a matriz com `OPENCLAW_SKIP_DOCKER_BUILD=1`. O workflow agendado live/E2E executa diariamente a suíte Docker completa do caminho de release. Testes Docker de QR e instalador mantêm seus próprios Dockerfiles focados em instalação. Um job separado `docker-e2e-fast` executa o perfil Docker limitado de plugins integrados sob um timeout de comando de 120 segundos: reparo de dependência no setup-entry mais isolamento sintético de falha do bundled-loader. A matriz completa de atualização/canal integrado permanece manual/suíte completa porque realiza repetidas passagens reais de atualização npm e reparo doctor.
|
||||
Edições de workflow de CI validam o grafo de CI do Node mais o lint de workflow, mas não forçam, por si só, builds nativos de Windows, Android ou macOS; essas lanes de plataforma continuam com escopo restrito a alterações no código-fonte da plataforma.
|
||||
As verificações Node do Windows têm escopo restrito a wrappers específicos de processo/caminho do Windows, helpers de npm/pnpm/UI runner, configuração do gerenciador de pacotes e superfícies de workflow de CI que executam essa lane; alterações não relacionadas em código-fonte, plugin, install-smoke e apenas testes permanecem nas lanes Node do Linux para não reservar um worker Windows de 16 vCPU para cobertura que já é exercida pelos shards normais de teste.
|
||||
O workflow separado `install-smoke` reutiliza o mesmo script de escopo por meio do seu próprio job `preflight`. Ele calcula `run_install_smoke` a partir do sinal mais restrito de alteração de smoke, então o smoke de Docker/instalação é executado para alterações relevantes a instalação, empacotamento, contêiner, produção de extensões bundled e superfícies centrais de plugin/channel/gateway/Plugin SDK que os jobs de smoke em Docker exercitam. Edições apenas em testes e apenas em docs não reservam workers Docker. Seu smoke do pacote QR força a camada Docker `pnpm install` a ser reexecutada preservando o cache da store pnpm do BuildKit, então ele ainda exercita a instalação sem baixar novamente as dependências em cada execução. Seu gateway-network e2e reutiliza a imagem de runtime compilada anteriormente no job, então adiciona cobertura real de WebSocket entre contêineres sem adicionar outro build Docker. O `test:docker:all` local faz prebuild de uma imagem compartilhada de teste ao vivo e uma imagem compartilhada do app compilado em `scripts/e2e/Dockerfile`, depois executa as lanes smoke live/E2E em paralelo com `OPENCLAW_SKIP_DOCKER_BUILD=1`; ajuste a concorrência padrão de 4 com `OPENCLAW_DOCKER_ALL_PARALLELISM`. O agregador local para de agendar novas lanes no pool após a primeira falha por padrão, e cada lane tem um timeout de 120 minutos, substituível com `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`. Lanes sensíveis à inicialização ou ao provider são executadas exclusivamente após o pool paralelo. O workflow reutilizável live/E2E espelha o padrão de imagem compartilhada ao compilar e publicar uma imagem Docker E2E única no GHCR com tag SHA antes da matriz Docker, então executa a matriz com `OPENCLAW_SKIP_DOCKER_BUILD=1`. O workflow live/E2E agendado executa diariamente a suíte Docker completa do caminho de release. Os testes Docker de QR e installer mantêm seus próprios Dockerfiles focados em instalação. Um job separado `docker-e2e-fast` executa o perfil Docker limitado de bundled-plugin sob um timeout de comando de 120 segundos: reparo de dependências em setup-entry mais isolamento sintético de falha do bundled-loader. A matriz completa de bundled update/channel continua manual/full-suite porque realiza passagens repetidas reais de atualização npm e reparo com doctor.
|
||||
|
||||
A lógica local de lane alterada fica em `scripts/changed-lanes.mjs` e é executada por `scripts/check-changed.mjs`. Esse gate local é mais rigoroso quanto aos limites de arquitetura do que o escopo amplo de plataforma da CI: alterações de produção do core executam typecheck de produção do core mais testes do core, alterações somente em testes do core executam apenas typecheck/testes de teste do core, alterações de produção de extensão executam typecheck de produção de extensão mais testes de extensão, e alterações somente em testes de extensão executam apenas typecheck/testes de teste de extensão. Alterações no Plugin SDK público ou no contrato de plugin expandem para validação de extensões porque as extensões dependem desses contratos do core. Bumps de versão apenas em metadados de release executam verificações direcionadas de versão/configuração/dependência raiz. Alterações desconhecidas em raiz/configuração falham para o lado seguro em todas as lanes.
|
||||
A lógica local de lanes alteradas fica em `scripts/changed-lanes.mjs` e é executada por `scripts/check-changed.mjs`. Esse gate local é mais estrito quanto a limites de arquitetura do que o amplo escopo de plataforma da CI: alterações de produção do core executam typecheck de produção do core mais testes do core, alterações apenas em testes do core executam apenas typecheck/testes de teste do core, alterações de produção de extensões executam typecheck de produção de extensões mais testes de extensões, e alterações apenas em testes de extensões executam apenas typecheck/testes de teste de extensões. Alterações no Plugin SDK público ou em plugin-contract expandem para validação de extensões porque as extensões dependem desses contratos centrais. Incrementos de versão apenas em metadados de release executam verificações direcionadas de versão/config/dependências de raiz. Alterações desconhecidas em raiz/config falham com segurança para todas as lanes.
|
||||
|
||||
Em pushes, a matriz `checks` adiciona a lane `compat-node22` apenas para push. Em pull requests, essa lane é ignorada e a matriz continua focada nas lanes normais de teste/canal.
|
||||
Em pushes, a matriz `checks` adiciona a lane `compat-node22`, exclusiva de push. Em pull requests, essa lane é ignorada e a matriz permanece focada nas lanes normais de teste/channel.
|
||||
|
||||
As famílias mais lentas de testes Node são divididas ou balanceadas para que cada job permaneça pequeno: contratos de canal dividem cobertura de registro e core em seis shards ponderados no total, testes de plugins integrados são balanceados em seis workers de extensão, auto-reply roda como três workers balanceados em vez de seis workers minúsculos, e configurações agentic de Gateway/plugin são distribuídas pelos jobs Node agentic já existentes somente de código-fonte em vez de esperarem por artefatos construídos. Testes amplos de navegador, QA, mídia e plugins diversos usam suas configurações dedicadas do Vitest em vez do catch-all compartilhado de plugin. A lane ampla de agents usa o agendador compartilhado de paralelismo por arquivo do Vitest porque é dominada por import/agendamento em vez de pertencer a um único arquivo de teste lento. `runtime-config` roda com o shard `infra core-runtime` para evitar que o shard de runtime compartilhado fique com a cauda. `check-additional` mantém juntos o trabalho de compile/canary de limite de pacote e separa arquitetura de topologia de runtime da cobertura de gateway watch; o shard de boundary guard executa seus pequenos guards independentes concorrentemente dentro de um único job. Gateway watch, testes de canal e o shard de limite de suporte do core executam concorrentemente dentro de `build-artifacts` depois que `dist/` e `dist-runtime/` já foram construídos, mantendo seus antigos nomes de verificação como jobs leves de verificação e evitando dois workers Blacksmith extras e uma segunda fila de consumidor de artefatos.
|
||||
A CI Android executa tanto `testPlayDebugUnitTest` quanto `testThirdPartyDebugUnitTest`, e depois faz build do APK debug Play. A variante third-party não tem source set nem manifest separado; sua lane de teste unitário ainda compila essa variante com as flags BuildConfig de SMS/log de chamadas, evitando ao mesmo tempo um job duplicado de empacotamento de APK debug em cada push relevante para Android.
|
||||
`extension-fast` é apenas para PR porque execuções em push já executam os shards completos de plugins integrados. Isso mantém feedback de plugin alterado para revisões sem reservar um worker Blacksmith extra em `main` para cobertura já presente em `checks-node-extensions`.
|
||||
As famílias de teste Node mais lentas são divididas ou balanceadas para que cada job permaneça pequeno sem reservar runners em excesso: contratos de channel são executados como três shards ponderados, testes de bundled plugin são balanceados em seis workers de extensões, pequenas lanes unitárias do core são pareadas, auto-reply é executado como três workers balanceados em vez de seis workers minúsculos, e configs agentic de gateway/plugin são distribuídas pelos jobs Node agentic existentes apenas de código-fonte, em vez de esperar por artefatos compilados. Testes amplos de browser, QA, mídia e plugins diversos usam suas configs Vitest dedicadas em vez do catch-all compartilhado de plugin. A lane ampla de agents usa o agendador compartilhado de paralelismo por arquivo do Vitest porque é dominada por import/agendamento, em vez de pertencer a um único arquivo de teste lento. `runtime-config` é executado com o shard infra core-runtime para impedir que o shard de runtime compartilhado fique com a cauda. `check-additional` mantém juntos o trabalho compile/canary de package-boundary e separa a arquitetura de topologia de runtime da cobertura de gateway watch; o shard de boundary guard executa seus pequenos guards independentes simultaneamente dentro de um único job. Gateway watch, testes de channel e o shard de support-boundary do core são executados simultaneamente dentro de `build-artifacts` depois que `dist/` e `dist-runtime/` já foram compilados, mantendo seus nomes antigos de check como jobs verificadores leves e evitando dois workers Blacksmith extras e uma segunda fila de consumidores de artefatos.
|
||||
A CI de Android executa tanto `testPlayDebugUnitTest` quanto `testThirdPartyDebugUnitTest`, depois compila o APK debug Play. O flavor third-party não tem source set nem manifest separado; sua lane de teste unitário ainda compila esse flavor com os flags SMS/call-log do BuildConfig, enquanto evita um job duplicado de empacotamento de APK debug em cada push relevante para Android.
|
||||
`extension-fast` é exclusivo para PR porque execuções em push já executam os shards completos de bundled plugin. Isso mantém o feedback de plugins alterados para revisão sem reservar um worker Blacksmith extra em `main` para cobertura já presente em `checks-node-extensions`.
|
||||
|
||||
O GitHub pode marcar jobs substituídos como `cancelled` quando um push mais novo chega na mesma ref de PR ou `main`. Trate isso como ruído de CI, a menos que a execução mais recente da mesma ref também esteja falhando. Verificações agregadas de shard usam `!cancelled() && always()` para que ainda informem falhas normais de shard, mas não entrem na fila depois que o workflow inteiro já tiver sido substituído.
|
||||
O GitHub pode marcar jobs substituídos como `cancelled` quando um push mais recente chega no mesmo PR ou ref `main`. Trate isso como ruído de CI, a menos que a execução mais recente para a mesma ref também esteja falhando. Verificações agregadas de shards usam `!cancelled() && always()` para que ainda relatem falhas normais de shard, mas não entrem na fila depois que todo o workflow já tiver sido substituído.
|
||||
A chave de concorrência da CI é versionada (`CI-v7-*`) para que um zumbi do lado do GitHub em um grupo de fila antigo não possa bloquear indefinidamente execuções mais novas na main.
|
||||
|
||||
## Runners
|
||||
|
||||
| Runner | Jobs |
|
||||
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `ubuntu-24.04` | `preflight`, jobs rápidos de segurança e agregadores (`security-scm-fast`, `security-dependency-audit`, `security-fast`), verificações rápidas de protocolo/contrato/integrados, verificações fragmentadas de contratos de canal, shards de `check` exceto lint, shards e agregadores de `check-additional`, verificadores agregados de testes Node, verificações de docs, Skills em Python, workflow-sanity, labeler, auto-response; o preflight de install-smoke também usa Ubuntu hospedado pelo GitHub para que a matriz Blacksmith possa entrar na fila mais cedo |
|
||||
| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, shards de teste Node em Linux, shards de teste de plugins integrados, `android` |
|
||||
| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`, que continua sensível o suficiente a CPU a ponto de 8 vCPU custarem mais do que economizaram; builds Docker de install-smoke, em que o tempo de fila de 32 vCPU custou mais do que economizou |
|
||||
| `ubuntu-24.04` | `preflight`, jobs rápidos de segurança e agregadores (`security-scm-fast`, `security-dependency-audit`, `security-fast`), verificações rápidas de protocolo/contrato/bundled, verificações fragmentadas de contratos de channel, shards de `check` exceto lint, shards e agregadores de `check-additional`, verificadores agregados de testes Node, verificações de docs, Skills em Python, workflow-sanity, labeler, auto-response; o preflight de install-smoke também usa Ubuntu hospedado pelo GitHub para que a matriz Blacksmith possa entrar na fila mais cedo |
|
||||
| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, shards de testes Node no Linux, shards de testes de bundled plugin, `android` |
|
||||
| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`, que continua sensível o suficiente a CPU para que 8 vCPU custem mais do que economizam; builds Docker de install-smoke, em que o custo de tempo de fila de 32 vCPU foi maior do que a economia |
|
||||
| `blacksmith-16vcpu-windows-2025` | `checks-windows` |
|
||||
| `blacksmith-6vcpu-macos-latest` | `macos-node` em `openclaw/openclaw`; forks usam `macos-latest` como fallback |
|
||||
| `blacksmith-12vcpu-macos-latest` | `macos-swift` em `openclaw/openclaw`; forks usam `macos-latest` como fallback |
|
||||
| `blacksmith-6vcpu-macos-latest` | `macos-node` em `openclaw/openclaw`; forks recorrem a `macos-latest` |
|
||||
| `blacksmith-12vcpu-macos-latest` | `macos-swift` em `openclaw/openclaw`; forks recorrem a `macos-latest` |
|
||||
|
||||
## Equivalentes locais
|
||||
|
||||
```bash
|
||||
pnpm changed:lanes # inspeciona o classificador local de lanes alteradas para origin/main...HEAD
|
||||
pnpm check:changed # gate local inteligente: typecheck/lint/testes alterados por lane de limite
|
||||
pnpm check # gate local rápido: tsgo de produção + lint fragmentado + guards rápidos paralelos
|
||||
pnpm check # gate local rápido: tsgo de produção + lint fragmentado + guards rápidos em paralelo
|
||||
pnpm check:test-types
|
||||
pnpm check:timed # mesmo gate com tempos por etapa
|
||||
pnpm build:strict-smoke
|
||||
@ -101,7 +100,8 @@ pnpm test:gateway:watch-regression
|
||||
pnpm test # testes Vitest
|
||||
pnpm test:channels
|
||||
pnpm test:contracts:channels
|
||||
pnpm check:docs # formatação + lint + links quebrados das docs
|
||||
pnpm build # faz build de dist quando as lanes de artefato/build-smoke da CI forem relevantes
|
||||
node scripts/ci-run-timings.mjs <run-id> # resume tempo total, tempo em fila e jobs mais lentos
|
||||
pnpm check:docs # formatação + lint + links quebrados de docs
|
||||
pnpm build # compila dist quando as lanes artifact/build-smoke da CI forem relevantes
|
||||
node scripts/ci-run-timings.mjs <run-id> # resume tempo total, tempo em fila e os jobs mais lentos
|
||||
node scripts/ci-run-timings.mjs --recent 10 # compara execuções recentes bem-sucedidas da CI na main
|
||||
```
|
||||
|
||||
@ -1,14 +1,14 @@
|
||||
---
|
||||
read_when:
|
||||
- Depurando autenticação de modelo ou expiração de OAuth
|
||||
- Documentando autenticação ou armazenamento de credenciais
|
||||
summary: 'Autenticação de modelo: OAuth, chaves de API, reutilização do Claude CLI e setup-token da Anthropic'
|
||||
- Depuração da autenticação do modelo ou expiração do OAuth
|
||||
- Documentação da autenticação ou do armazenamento de credenciais
|
||||
summary: 'Autenticação de modelo: OAuth, chaves de API, reutilização do Claude CLI e token de configuração do Anthropic'
|
||||
title: Autenticação
|
||||
x-i18n:
|
||||
generated_at: "2026-04-07T05:27:09Z"
|
||||
generated_at: "2026-04-23T14:55:09Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 9db0ad9eccd7e3e3ca328adaad260bc4288a8ccdbe2dc0c24d9fd049b7ab9231
|
||||
source_hash: 37a7c20872b915d1d079f0578c933e43cbdb97eca1c60d8c4e6e5137ca83f8b2
|
||||
source_path: gateway/authentication.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -16,25 +16,20 @@ x-i18n:
|
||||
# Autenticação (Provedores de modelo)
|
||||
|
||||
<Note>
|
||||
Esta página cobre a autenticação de **provedor de modelo** (chaves de API, OAuth, reutilização do Claude CLI e setup-token da Anthropic). Para autenticação de **conexão com o gateway** (token, senha, trusted-proxy), consulte [Configuration](/pt-BR/gateway/configuration) e [Trusted Proxy Auth](/pt-BR/gateway/trusted-proxy-auth).
|
||||
Esta página cobre a autenticação de **provedor de modelo** (chaves de API, OAuth, reutilização do Claude CLI e token de configuração do Anthropic). Para a autenticação de **conexão do gateway** (token, senha, trusted-proxy), consulte [Configuration](/pt-BR/gateway/configuration) e [Trusted Proxy Auth](/pt-BR/gateway/trusted-proxy-auth).
|
||||
</Note>
|
||||
|
||||
O OpenClaw oferece suporte a OAuth e chaves de API para provedores de modelo. Para hosts de gateway
|
||||
sempre ativos, chaves de API geralmente são a opção mais previsível. Fluxos de
|
||||
assinatura/OAuth também são compatíveis quando correspondem ao modelo de conta do seu provedor.
|
||||
O OpenClaw oferece suporte a OAuth e chaves de API para provedores de modelo. Para hosts de gateway sempre ativos, chaves de API geralmente são a opção mais previsível. Fluxos de assinatura/OAuth também são compatíveis quando correspondem ao modelo de conta do seu provedor.
|
||||
|
||||
Consulte [/concepts/oauth](/pt-BR/concepts/oauth) para o fluxo completo de OAuth e o layout
|
||||
de armazenamento.
|
||||
Para autenticação baseada em SecretRef (provedores `env`/`file`/`exec`), consulte [Gerenciamento de segredos](/pt-BR/gateway/secrets).
|
||||
Consulte [/concepts/oauth](/pt-BR/concepts/oauth) para o fluxo completo de OAuth e o layout de armazenamento.
|
||||
Para autenticação baseada em SecretRef (provedores `env`/`file`/`exec`), consulte [Secrets Management](/pt-BR/gateway/secrets).
|
||||
Para regras de elegibilidade de credenciais/códigos de motivo usadas por `models status --probe`, consulte
|
||||
[Semântica de credenciais de autenticação](/pt-BR/auth-credential-semantics).
|
||||
|
||||
## Configuração recomendada (chave de API, qualquer provedor)
|
||||
|
||||
Se você estiver executando um gateway de longa duração, comece com uma chave de API para o provedor
|
||||
escolhido.
|
||||
Para Anthropic especificamente, a autenticação por chave de API ainda é a configuração de servidor
|
||||
mais previsível, mas o OpenClaw também oferece suporte à reutilização de um login local do Claude CLI.
|
||||
Se você estiver executando um gateway de longa duração, comece com uma chave de API para o provedor escolhido.
|
||||
Especificamente para Anthropic, a autenticação por chave de API ainda é a configuração de servidor mais previsível, mas o OpenClaw também oferece suporte à reutilização de um login local do Claude CLI.
|
||||
|
||||
1. Crie uma chave de API no console do seu provedor.
|
||||
2. Coloque-a no **host do gateway** (a máquina que executa `openclaw gateway`).
|
||||
@ -53,7 +48,7 @@ cat >> ~/.openclaw/.env <<'EOF'
|
||||
EOF
|
||||
```
|
||||
|
||||
Em seguida, reinicie o daemon (ou reinicie seu processo do Gateway) e verifique novamente:
|
||||
Em seguida, reinicie o daemon (ou reinicie o processo do Gateway) e verifique novamente:
|
||||
|
||||
```bash
|
||||
openclaw models status
|
||||
@ -61,42 +56,54 @@ openclaw doctor
|
||||
```
|
||||
|
||||
Se você preferir não gerenciar variáveis de ambiente por conta própria, o onboarding pode armazenar
|
||||
chaves de API para uso do daemon: `openclaw onboard`.
|
||||
chaves de API para uso pelo daemon: `openclaw onboard`.
|
||||
|
||||
Consulte [Help](/pt-BR/help) para detalhes sobre herança de ambiente (`env.shellEnv`,
|
||||
`~/.openclaw/.env`, systemd/launchd).
|
||||
|
||||
## Anthropic: compatibilidade com Claude CLI e token
|
||||
|
||||
A autenticação por setup-token da Anthropic ainda está disponível no OpenClaw como um caminho
|
||||
compatível de token. Desde então, a equipe da Anthropic nos informou que o uso do Claude CLI no estilo OpenClaw é
|
||||
permitido novamente, então o OpenClaw trata a reutilização do Claude CLI e o uso de `claude -p` como
|
||||
autorizados para esta integração, a menos que a Anthropic publique uma nova política. Quando
|
||||
a reutilização do Claude CLI está disponível no host, esse agora é o caminho preferido.
|
||||
A autenticação por token de configuração do Anthropic continua disponível no OpenClaw como um caminho de token compatível. Desde então, a equipe da Anthropic nos informou que o uso do Claude CLI no estilo OpenClaw é permitido novamente, então o OpenClaw trata a reutilização do Claude CLI e o uso de `claude -p` como autorizados para esta integração, a menos que a Anthropic publique uma nova política. Quando a reutilização do Claude CLI está disponível no host, esse agora é o caminho preferido.
|
||||
|
||||
Para hosts de gateway de longa duração, uma chave de API da Anthropic ainda é a configuração
|
||||
mais previsível. Se você quiser reutilizar um login existente do Claude no mesmo host, use o
|
||||
caminho do Anthropic Claude CLI no onboarding/configuração.
|
||||
Para hosts de gateway de longa duração, uma chave de API do Anthropic ainda é a configuração mais previsível. Se você quiser reutilizar um login existente do Claude no mesmo host, use o caminho do Anthropic Claude CLI em onboarding/configure.
|
||||
|
||||
Entrada manual de token (qualquer provedor; grava `auth-profiles.json` + atualiza a configuração):
|
||||
Configuração de host recomendada para reutilização do Claude CLI:
|
||||
|
||||
```bash
|
||||
# Execute no host do gateway
|
||||
claude auth login
|
||||
claude auth status --text
|
||||
openclaw models auth login --provider anthropic --method cli --set-default
|
||||
```
|
||||
|
||||
Esta é uma configuração em duas etapas:
|
||||
|
||||
1. Faça login do próprio Claude Code no Anthropic no host do gateway.
|
||||
2. Diga ao OpenClaw para alternar a seleção de modelo Anthropic para o backend local `claude-cli`
|
||||
e armazenar o perfil de autenticação correspondente do OpenClaw.
|
||||
|
||||
Se `claude` não estiver em `PATH`, instale o Claude Code primeiro ou defina
|
||||
`agents.defaults.cliBackends.claude-cli.command` para o caminho real do binário.
|
||||
|
||||
Entrada manual de token (qualquer provedor; grava em `auth-profiles.json` + atualiza a configuração):
|
||||
|
||||
```bash
|
||||
openclaw models auth paste-token --provider openrouter
|
||||
```
|
||||
|
||||
Refs de perfil de autenticação também são compatíveis para credenciais estáticas:
|
||||
Referências de perfil de autenticação também são compatíveis com credenciais estáticas:
|
||||
|
||||
- credenciais `api_key` podem usar `keyRef: { source, provider, id }`
|
||||
- credenciais `token` podem usar `tokenRef: { source, provider, id }`
|
||||
- perfis em modo OAuth não oferecem suporte a credenciais SecretRef; se `auth.profiles.<id>.mode` estiver definido como `"oauth"`, a entrada `keyRef`/`tokenRef` com respaldo em SecretRef para esse perfil será rejeitada.
|
||||
- Perfis no modo OAuth não oferecem suporte a credenciais SecretRef; se `auth.profiles.<id>.mode` estiver definido como `"oauth"`, a entrada `keyRef`/`tokenRef` com suporte de SecretRef para esse perfil será rejeitada.
|
||||
|
||||
Verificação amigável para automação (saída `1` quando expirado/ausente, `2` quando prestes a expirar):
|
||||
Verificação compatível com automação (saída `1` quando expirado/ausente, `2` quando está expirando):
|
||||
|
||||
```bash
|
||||
openclaw models status --check
|
||||
```
|
||||
|
||||
Sondagens de autenticação ao vivo:
|
||||
Sondagens de autenticação em tempo real:
|
||||
|
||||
```bash
|
||||
openclaw models status --probe
|
||||
@ -104,12 +111,12 @@ openclaw models status --probe
|
||||
|
||||
Observações:
|
||||
|
||||
- Linhas de sonda podem vir de perfis de autenticação, credenciais de ambiente ou `models.json`.
|
||||
- Se `auth.order.<provider>` explícito omitir um perfil armazenado, a sonda relatará
|
||||
- Linhas de sondagem podem vir de perfis de autenticação, credenciais de ambiente ou `models.json`.
|
||||
- Se `auth.order.<provider>` explícito omitir um perfil armazenado, a sondagem reportará
|
||||
`excluded_by_auth_order` para esse perfil em vez de tentar usá-lo.
|
||||
- Se a autenticação existir, mas o OpenClaw não conseguir resolver um candidato de modelo sondável para
|
||||
esse provedor, a sonda relatará `status: no_model`.
|
||||
- Cooldowns de limite de taxa podem ser específicos do modelo. Um perfil em cooldown para um
|
||||
- Se a autenticação existir, mas o OpenClaw não conseguir resolver um candidato sondável de modelo para
|
||||
esse provedor, a sondagem reportará `status: no_model`.
|
||||
- Resfriamentos por limite de taxa podem ser específicos por modelo. Um perfil em resfriamento para um
|
||||
modelo ainda pode ser utilizável para um modelo irmão no mesmo provedor.
|
||||
|
||||
Scripts operacionais opcionais (systemd/Termux) estão documentados aqui:
|
||||
@ -117,15 +124,15 @@ Scripts operacionais opcionais (systemd/Termux) estão documentados aqui:
|
||||
|
||||
## Observação sobre Anthropic
|
||||
|
||||
O backend `claude-cli` da Anthropic é compatível novamente.
|
||||
O backend `claude-cli` do Anthropic voltou a ser compatível.
|
||||
|
||||
- A equipe da Anthropic nos informou que esse caminho de integração do OpenClaw é permitido novamente.
|
||||
- Portanto, o OpenClaw trata a reutilização do Claude CLI e o uso de `claude -p` como autorizados
|
||||
para execuções com respaldo da Anthropic, a menos que a Anthropic publique uma nova política.
|
||||
- Chaves de API da Anthropic continuam sendo a escolha mais previsível para hosts de gateway
|
||||
de longa duração e controle explícito de cobrança no lado do servidor.
|
||||
para execuções com Anthropic, a menos que a Anthropic publique uma nova política.
|
||||
- Chaves de API do Anthropic continuam sendo a escolha mais previsível para hosts de gateway de longa
|
||||
duração e controle explícito de faturamento no lado do servidor.
|
||||
|
||||
## Verificando o status da autenticação do modelo
|
||||
## Verificação do status de autenticação do modelo
|
||||
|
||||
```bash
|
||||
openclaw models status
|
||||
@ -134,7 +141,7 @@ openclaw doctor
|
||||
|
||||
## Comportamento de rotação de chave de API (gateway)
|
||||
|
||||
Alguns provedores oferecem suporte a tentar novamente uma solicitação com chaves alternativas quando uma chamada de API
|
||||
Alguns provedores oferecem suporte a repetir uma solicitação com chaves alternativas quando uma chamada de API
|
||||
atinge um limite de taxa do provedor.
|
||||
|
||||
- Ordem de prioridade:
|
||||
@ -142,7 +149,7 @@ atinge um limite de taxa do provedor.
|
||||
- `<PROVIDER>_API_KEYS`
|
||||
- `<PROVIDER>_API_KEY`
|
||||
- `<PROVIDER>_API_KEY_*`
|
||||
- Provedores Google também incluem `GOOGLE_API_KEY` como fallback adicional.
|
||||
- Provedores do Google também incluem `GOOGLE_API_KEY` como fallback adicional.
|
||||
- A mesma lista de chaves é deduplicada antes do uso.
|
||||
- O OpenClaw tenta novamente com a próxima chave apenas para erros de limite de taxa (por exemplo
|
||||
`429`, `rate_limit`, `quota`, `resource exhausted`, `Too many concurrent
|
||||
@ -151,7 +158,7 @@ requests`, `ThrottlingException`, `concurrency limit reached`, ou
|
||||
- Erros que não sejam de limite de taxa não são tentados novamente com chaves alternativas.
|
||||
- Se todas as chaves falharem, o erro final da última tentativa será retornado.
|
||||
|
||||
## Controlando qual credencial é usada
|
||||
## Controlar qual credencial é usada
|
||||
|
||||
### Por sessão (comando de chat)
|
||||
|
||||
@ -159,7 +166,7 @@ Use `/model <alias-or-id>@<profileId>` para fixar uma credencial específica de
|
||||
|
||||
Use `/model` (ou `/model list`) para um seletor compacto; use `/model status` para a visualização completa (candidatos + próximo perfil de autenticação, além de detalhes do endpoint do provedor quando configurado).
|
||||
|
||||
### Por agente (substituição da CLI)
|
||||
### Por agente (substituição na CLI)
|
||||
|
||||
Defina uma substituição explícita da ordem de perfis de autenticação para um agente (armazenada no `auth-state.json` desse agente):
|
||||
|
||||
@ -169,25 +176,25 @@ openclaw models auth order set --provider anthropic anthropic:default
|
||||
openclaw models auth order clear --provider anthropic
|
||||
```
|
||||
|
||||
Use `--agent <id>` para direcionar um agente específico; omita-o para usar o agente padrão configurado.
|
||||
Ao depurar problemas de ordem, `openclaw models status --probe` mostra perfis
|
||||
armazenados omitidos como `excluded_by_auth_order` em vez de ignorá-los silenciosamente.
|
||||
Ao depurar problemas de cooldown, lembre-se de que cooldowns de limite de taxa podem estar vinculados
|
||||
a um ID de modelo, e não ao perfil inteiro do provedor.
|
||||
Use `--agent <id>` para direcionar a um agente específico; omita-o para usar o agente padrão configurado.
|
||||
Ao depurar problemas de ordem, `openclaw models status --probe` mostra perfis armazenados omitidos
|
||||
como `excluded_by_auth_order` em vez de ignorá-los silenciosamente.
|
||||
Ao depurar problemas de resfriamento, lembre-se de que resfriamentos por limite de taxa podem estar vinculados
|
||||
a um ID de modelo em vez de a todo o perfil do provedor.
|
||||
|
||||
## Solução de problemas
|
||||
|
||||
### "Nenhuma credencial encontrada"
|
||||
|
||||
Se o perfil da Anthropic estiver ausente, configure uma chave de API da Anthropic no
|
||||
**host do gateway** ou configure o caminho de setup-token da Anthropic, e depois verifique novamente:
|
||||
Se o perfil do Anthropic estiver ausente, configure uma chave de API do Anthropic no
|
||||
**host do gateway** ou configure o caminho de token de configuração do Anthropic, depois verifique novamente:
|
||||
|
||||
```bash
|
||||
openclaw models status
|
||||
```
|
||||
|
||||
### Token prestes a expirar/expirado
|
||||
### Token expirando/expirado
|
||||
|
||||
Execute `openclaw models status` para confirmar qual perfil está prestes a expirar. Se um
|
||||
perfil de token da Anthropic estiver ausente ou expirado, atualize essa configuração por meio do
|
||||
setup-token ou migre para uma chave de API da Anthropic.
|
||||
Execute `openclaw models status` para confirmar qual perfil está expirando. Se um
|
||||
perfil de token do Anthropic estiver ausente ou expirado, atualize essa configuração via
|
||||
token de configuração ou migre para uma chave de API do Anthropic.
|
||||
|
||||
@ -1,40 +1,40 @@
|
||||
---
|
||||
read_when:
|
||||
- Você quer um fallback confiável quando provedores de API falham
|
||||
- Você quer um fallback confiável quando os provedores de API falham
|
||||
- Você está executando o Codex CLI ou outras CLIs locais de IA e quer reutilizá-las
|
||||
- Você quer entender a bridge MCP loopback para acesso a ferramentas do backend de CLI
|
||||
summary: 'Backends de CLI: fallback de CLI local de IA com bridge opcional de ferramenta MCP'
|
||||
- Você quer entender a ponte MCP de loopback para acesso a ferramentas do backend de CLI
|
||||
summary: 'Backends de CLI: fallback local de CLI de IA com ponte opcional de ferramenta MCP'
|
||||
title: Backends de CLI
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T14:02:31Z"
|
||||
generated_at: "2026-04-23T14:55:05Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 475923b36e4580d3e4e57014ff2e6b89e9eb52c11b0a0ab1fc8241655b07836e
|
||||
source_hash: ff7458d18b8a5b716930579241177917fd3edffcf7f6e211c7d570cf76519316
|
||||
source_path: gateway/cli-backends.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Backends de CLI (runtime de fallback)
|
||||
|
||||
O OpenClaw pode executar **CLIs locais de IA** como um **fallback somente de texto** quando provedores de API estão fora do ar,
|
||||
com rate limit ou temporariamente se comportando mal. Isso é intencionalmente conservador:
|
||||
O OpenClaw pode executar **CLIs locais de IA** como um **fallback somente de texto** quando os provedores de API estão fora do ar,
|
||||
com limite de taxa ou temporariamente se comportando mal. Isso é intencionalmente conservador:
|
||||
|
||||
- **As ferramentas do OpenClaw não são injetadas diretamente**, mas backends com `bundleMcp: true`
|
||||
podem receber ferramentas do Gateway por meio de uma bridge MCP loopback.
|
||||
- **Streaming JSONL** para CLIs que o suportam.
|
||||
- **Sessões são compatíveis** (para que turnos de continuação permaneçam coerentes).
|
||||
podem receber ferramentas do Gateway por meio de uma ponte MCP de loopback.
|
||||
- **Streaming JSONL** para CLIs que oferecem suporte.
|
||||
- **Sessões são suportadas** (para que as interações de continuação permaneçam coerentes).
|
||||
- **Imagens podem ser repassadas** se a CLI aceitar caminhos de imagem.
|
||||
|
||||
Isso foi projetado como uma **rede de segurança** em vez de um caminho principal. Use quando você
|
||||
quiser respostas de texto “sempre funcionam” sem depender de APIs externas.
|
||||
quiser respostas de texto do tipo “sempre funciona” sem depender de APIs externas.
|
||||
|
||||
Se você quiser um runtime de harness completo com controles de sessão ACP, tarefas em segundo plano,
|
||||
vinculação de thread/conversa e sessões externas persistentes de codificação, use
|
||||
[Agentes ACP](/pt-BR/tools/acp-agents). Backends de CLI não são ACP.
|
||||
[ACP Agents](/pt-BR/tools/acp-agents). Os backends de CLI não são ACP.
|
||||
|
||||
## Início rápido para iniciantes
|
||||
## Início rápido amigável para iniciantes
|
||||
|
||||
Você pode usar o Codex CLI **sem nenhuma configuração** (o plugin OpenAI integrado
|
||||
Você pode usar o Codex CLI **sem nenhuma configuração** (o Plugin OpenAI empacotado
|
||||
registra um backend padrão):
|
||||
|
||||
```bash
|
||||
@ -60,14 +60,14 @@ caminho do comando:
|
||||
|
||||
É só isso. Nenhuma chave, nenhuma configuração extra de autenticação além da própria CLI.
|
||||
|
||||
Se você usar um backend de CLI integrado como **provedor principal de mensagens** em um
|
||||
host de Gateway, o OpenClaw agora carrega automaticamente o plugin integrado responsável quando sua configuração
|
||||
faz referência explícita a esse backend em uma referência de modelo ou em
|
||||
Se você usar um backend de CLI empacotado como o **provedor principal de mensagens** em um
|
||||
host do Gateway, o OpenClaw agora carrega automaticamente o Plugin empacotado proprietário quando sua configuração
|
||||
faz referência explicitamente a esse backend em uma referência de modelo ou em
|
||||
`agents.defaults.cliBackends`.
|
||||
|
||||
## Usando como fallback
|
||||
|
||||
Adicione um backend de CLI à sua lista de fallback para que ele só rode quando os modelos primários falharem:
|
||||
Adicione um backend de CLI à sua lista de fallback para que ele só rode quando os modelos principais falharem:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -88,8 +88,8 @@ Adicione um backend de CLI à sua lista de fallback para que ele só rode quando
|
||||
|
||||
Observações:
|
||||
|
||||
- Se você usar `agents.defaults.models` (lista de permissões), também deverá incluir ali os modelos do backend de CLI.
|
||||
- Se o provedor primário falhar (autenticação, rate limits, timeouts), o OpenClaw
|
||||
- Se você usa `agents.defaults.models` (lista de permissões), deve incluir seus modelos de backend de CLI lá também.
|
||||
- Se o provedor principal falhar (autenticação, limites de taxa, timeouts), o OpenClaw
|
||||
tentará o backend de CLI em seguida.
|
||||
|
||||
## Visão geral da configuração
|
||||
@ -100,7 +100,7 @@ Todos os backends de CLI ficam em:
|
||||
agents.defaults.cliBackends
|
||||
```
|
||||
|
||||
Cada entrada é indexada por um **id de provedor** (por exemplo `codex-cli`, `my-cli`).
|
||||
Cada entrada é indexada por um **id de provedor** (por exemplo, `codex-cli`, `my-cli`).
|
||||
O id do provedor se torna o lado esquerdo da sua referência de modelo:
|
||||
|
||||
```
|
||||
@ -148,67 +148,79 @@ O id do provedor se torna o lado esquerdo da sua referência de modelo:
|
||||
## Como funciona
|
||||
|
||||
1. **Seleciona um backend** com base no prefixo do provedor (`codex-cli/...`).
|
||||
2. **Monta um prompt de sistema** usando o mesmo prompt + contexto de espaço de trabalho do OpenClaw.
|
||||
3. **Executa a CLI** com um id de sessão (se compatível) para que o histórico permaneça consistente.
|
||||
O backend integrado `claude-cli` mantém um processo stdio do Claude vivo por
|
||||
sessão OpenClaw e envia turnos de continuação pelo stdin stream-json.
|
||||
2. **Constrói um prompt de sistema** usando o mesmo prompt do OpenClaw + contexto do workspace.
|
||||
3. **Executa a CLI** com um id de sessão (se compatível), para que o histórico permaneça consistente.
|
||||
O backend empacotado `claude-cli` mantém um processo stdio do Claude vivo por
|
||||
sessão do OpenClaw e envia interações de continuação pelo stdin stream-json.
|
||||
4. **Analisa a saída** (JSON ou texto simples) e retorna o texto final.
|
||||
5. **Persiste ids de sessão** por backend, para que continuações reutilizem a mesma sessão da CLI.
|
||||
5. **Persiste ids de sessão** por backend, para que as continuações reutilizem a mesma sessão da CLI.
|
||||
|
||||
<Note>
|
||||
O backend integrado Anthropic `claude-cli` voltou a ser compatível. A equipe da Anthropic
|
||||
O backend empacotado Anthropic `claude-cli` voltou a ser suportado. A equipe da Anthropic
|
||||
nos informou que o uso do Claude CLI no estilo OpenClaw voltou a ser permitido, então o OpenClaw trata
|
||||
o uso de `claude -p` como autorizado para essa integração, a menos que a Anthropic publique
|
||||
uma nova política.
|
||||
</Note>
|
||||
|
||||
O backend integrado OpenAI `codex-cli` passa o prompt de sistema do OpenClaw via
|
||||
substituição de configuração `model_instructions_file` do Codex (`-c
|
||||
O backend empacotado OpenAI `codex-cli` passa o prompt de sistema do OpenClaw por meio
|
||||
da substituição de configuração `model_instructions_file` do Codex (`-c
|
||||
model_instructions_file="..."`). O Codex não expõe uma flag no estilo Claude
|
||||
`--append-system-prompt`, então o OpenClaw grava o prompt montado em um
|
||||
arquivo temporário para cada nova sessão do Codex CLI.
|
||||
|
||||
O backend integrado Anthropic `claude-cli` recebe o snapshot de Skills do OpenClaw
|
||||
de duas formas: o catálogo compacto de Skills do OpenClaw no prompt de sistema anexado e
|
||||
um plugin temporário do Claude Code passado com `--plugin-dir`. O plugin contém
|
||||
apenas as Skills elegíveis para aquele agent/sessão, de modo que o resolvedor nativo de Skills do Claude Code
|
||||
vê o mesmo conjunto filtrado que o OpenClaw anunciaria no prompt. Substituições de env/chave de API
|
||||
de Skill ainda são aplicadas pelo OpenClaw ao ambiente do processo filho durante a execução.
|
||||
O backend empacotado Anthropic `claude-cli` recebe o snapshot de Skills do OpenClaw
|
||||
de duas formas: o catálogo compacto de Skills do OpenClaw no prompt de sistema anexado, e
|
||||
um Plugin temporário do Claude Code passado com `--plugin-dir`. O Plugin contém
|
||||
apenas as Skills elegíveis para aquele agente/sessão, para que o resolvedor nativo de Skills do Claude Code
|
||||
veja o mesmo conjunto filtrado que o OpenClaw anunciaria no prompt. As substituições de env/chave de API de Skill
|
||||
ainda são aplicadas pelo OpenClaw ao ambiente do processo filho para a execução.
|
||||
|
||||
Antes que o OpenClaw possa usar o backend empacotado `claude-cli`, o próprio Claude Code
|
||||
já deve estar autenticado no mesmo host:
|
||||
|
||||
```bash
|
||||
claude auth login
|
||||
claude auth status --text
|
||||
openclaw models auth login --provider anthropic --method cli --set-default
|
||||
```
|
||||
|
||||
Use `agents.defaults.cliBackends.claude-cli.command` apenas quando o binário `claude`
|
||||
ainda não estiver no `PATH`.
|
||||
|
||||
## Sessões
|
||||
|
||||
- Se a CLI for compatível com sessões, defina `sessionArg` (por exemplo `--session-id`) ou
|
||||
- Se a CLI oferecer suporte a sessões, defina `sessionArg` (por exemplo, `--session-id`) ou
|
||||
`sessionArgs` (placeholder `{sessionId}`) quando o ID precisar ser inserido
|
||||
em várias flags.
|
||||
em múltiplas flags.
|
||||
- Se a CLI usar um **subcomando de retomada** com flags diferentes, defina
|
||||
`resumeArgs` (substitui `args` ao retomar) e opcionalmente `resumeOutput`
|
||||
(para retomadas não JSON).
|
||||
`resumeArgs` (substitui `args` ao retomar) e, opcionalmente, `resumeOutput`
|
||||
(para retomadas que não usam JSON).
|
||||
- `sessionMode`:
|
||||
- `always`: sempre envia um id de sessão (novo UUID se nenhum estiver armazenado).
|
||||
- `existing`: envia um id de sessão somente se um já tiver sido armazenado antes.
|
||||
- `always`: sempre envia um id de sessão (um novo UUID se não houver nenhum armazenado).
|
||||
- `existing`: só envia um id de sessão se um já tiver sido armazenado antes.
|
||||
- `none`: nunca envia um id de sessão.
|
||||
- `claude-cli` usa como padrão `liveSession: "claude-stdio"`, `output: "jsonl"`
|
||||
e `input: "stdin"` para que turnos de continuação reutilizem o processo Claude ativo enquanto
|
||||
- `claude-cli` usa por padrão `liveSession: "claude-stdio"`, `output: "jsonl"`,
|
||||
e `input: "stdin"` para que interações de continuação reutilizem o processo Claude ativo enquanto
|
||||
ele estiver ativo. stdio aquecido agora é o padrão, inclusive para configurações personalizadas
|
||||
que omitem campos de transporte. Se o Gateway reiniciar ou o processo ocioso
|
||||
encerrar, o OpenClaw retoma a partir do id de sessão Claude armazenado. Ids de sessão
|
||||
armazenados são verificados em relação a uma transcrição de projeto existente e legível antes da
|
||||
retomada, de modo que vinculações fantasmas são limpas com `reason=transcript-missing`
|
||||
em vez de iniciar silenciosamente uma nova sessão do Claude CLI sob `--resume`.
|
||||
- Sessões de CLI armazenadas são continuidade controlada pelo provedor. A redefinição implícita
|
||||
diária de sessão não as interrompe; `/reset` e políticas explícitas de `session.reset` ainda interrompem.
|
||||
encerrar, o OpenClaw retoma a partir do id de sessão do Claude armazenado. Os ids de sessão armazenados
|
||||
são verificados em relação a uma transcrição de projeto existente e legível antes da
|
||||
retomada, então vínculos fantasmas são limpos com `reason=transcript-missing`
|
||||
em vez de iniciar silenciosamente uma nova sessão do Claude CLI com `--resume`.
|
||||
- Sessões de CLI armazenadas são continuidade pertencente ao provedor. A redefinição implícita diária da sessão
|
||||
não as interrompe; `/reset` e políticas explícitas de `session.reset` ainda interrompem.
|
||||
|
||||
Observações sobre serialização:
|
||||
|
||||
- `serialize: true` mantém execuções da mesma lane em ordem.
|
||||
- A maioria das CLIs serializa em uma lane de provedor.
|
||||
- O OpenClaw abandona a reutilização da sessão de CLI armazenada quando a identidade de autenticação selecionada muda,
|
||||
incluindo mudança de id de perfil de autenticação, chave de API estática, token estático ou identidade
|
||||
de conta OAuth quando a CLI a expõe. Rotação de token de acesso e refresh OAuth
|
||||
- `serialize: true` mantém as execuções da mesma faixa em ordem.
|
||||
- A maioria das CLIs serializa em uma faixa de provedor.
|
||||
- O OpenClaw descarta a reutilização de sessão de CLI armazenada quando a identidade de autenticação selecionada muda,
|
||||
incluindo um id de perfil de autenticação alterado, chave de API estática alterada, token estático alterado ou
|
||||
identidade de conta OAuth alterada quando a CLI expõe uma. A rotação de token de acesso e de atualização OAuth
|
||||
não interrompe a sessão de CLI armazenada. Se uma CLI não expõe um id de conta OAuth estável,
|
||||
o OpenClaw deixa essa CLI impor permissões de retomada.
|
||||
o OpenClaw permite que essa CLI imponha as permissões de retomada.
|
||||
|
||||
## Imagens (pass-through)
|
||||
## Imagens (repasse)
|
||||
|
||||
Se a sua CLI aceitar caminhos de imagem, defina `imageArg`:
|
||||
|
||||
@ -218,17 +230,17 @@ imageMode: "repeat"
|
||||
```
|
||||
|
||||
O OpenClaw gravará imagens base64 em arquivos temporários. Se `imageArg` estiver definido, esses
|
||||
caminhos serão passados como argumentos da CLI. Se `imageArg` estiver ausente, o OpenClaw acrescenta os
|
||||
caminhos dos arquivos ao prompt (injeção de caminho), o que basta para CLIs que carregam
|
||||
arquivos locais automaticamente a partir de caminhos simples.
|
||||
caminhos serão passados como argumentos da CLI. Se `imageArg` estiver ausente, o OpenClaw acrescentará os
|
||||
caminhos dos arquivos ao prompt (injeção de caminho), o que é suficiente para CLIs que carregam
|
||||
automaticamente arquivos locais a partir de caminhos simples.
|
||||
|
||||
## Entradas / saídas
|
||||
|
||||
- `output: "json"` (padrão) tenta analisar JSON e extrair texto + id de sessão.
|
||||
- Para saída JSON da Gemini CLI, o OpenClaw lê o texto da resposta de `response` e
|
||||
o uso de `stats` quando `usage` estiver ausente ou vazio.
|
||||
- `output: "jsonl"` analisa streams JSONL (por exemplo Codex CLI `--json`) e extrai a mensagem final do agent mais identificadores de sessão
|
||||
quando presentes.
|
||||
- Para saída JSON do Gemini CLI, o OpenClaw lê o texto da resposta de `response` e
|
||||
uso de `stats` quando `usage` está ausente ou vazio.
|
||||
- `output: "jsonl"` analisa streams JSONL (por exemplo, Codex CLI `--json`) e extrai a mensagem final do agente mais
|
||||
identificadores de sessão quando presentes.
|
||||
- `output: "text"` trata stdout como a resposta final.
|
||||
|
||||
Modos de entrada:
|
||||
@ -237,9 +249,9 @@ Modos de entrada:
|
||||
- `input: "stdin"` envia o prompt via stdin.
|
||||
- Se o prompt for muito longo e `maxPromptArgChars` estiver definido, stdin será usado.
|
||||
|
||||
## Padrões (controlados por plugin)
|
||||
## Padrões (pertencentes ao Plugin)
|
||||
|
||||
O plugin OpenAI integrado também registra um padrão para `codex-cli`:
|
||||
O Plugin OpenAI empacotado também registra um padrão para `codex-cli`:
|
||||
|
||||
- `command: "codex"`
|
||||
- `args: ["exec","--json","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]`
|
||||
@ -250,7 +262,7 @@ O plugin OpenAI integrado também registra um padrão para `codex-cli`:
|
||||
- `imageArg: "--image"`
|
||||
- `sessionMode: "existing"`
|
||||
|
||||
O plugin Google integrado também registra um padrão para `google-gemini-cli`:
|
||||
O Plugin Google empacotado também registra um padrão para `google-gemini-cli`:
|
||||
|
||||
- `command: "gemini"`
|
||||
- `args: ["--output-format", "json", "--prompt", "{prompt}"]`
|
||||
@ -265,28 +277,28 @@ Pré-requisito: a Gemini CLI local deve estar instalada e disponível como
|
||||
`gemini` no `PATH` (`brew install gemini-cli` ou
|
||||
`npm install -g @google/gemini-cli`).
|
||||
|
||||
Observações sobre JSON da Gemini CLI:
|
||||
Observações sobre o JSON do Gemini CLI:
|
||||
|
||||
- O texto da resposta é lido do campo JSON `response`.
|
||||
- O uso recorre a `stats` quando `usage` estiver ausente ou vazio.
|
||||
- `stats.cached` é normalizado para `cacheRead` do OpenClaw.
|
||||
- O uso recorre a `stats` quando `usage` está ausente ou vazio.
|
||||
- `stats.cached` é normalizado em `cacheRead` do OpenClaw.
|
||||
- Se `stats.input` estiver ausente, o OpenClaw deriva tokens de entrada de
|
||||
`stats.input_tokens - stats.cached`.
|
||||
|
||||
Substitua apenas se necessário (comum: caminho `command` absoluto).
|
||||
Substitua apenas se necessário (comum: caminho absoluto de `command`).
|
||||
|
||||
## Padrões controlados por plugin
|
||||
## Padrões pertencentes ao Plugin
|
||||
|
||||
Os padrões de backend de CLI agora fazem parte da superfície de plugin:
|
||||
Os padrões de backend de CLI agora fazem parte da superfície do Plugin:
|
||||
|
||||
- Plugins os registram com `api.registerCliBackend(...)`.
|
||||
- O `id` do backend se torna o prefixo do provedor em referências de modelo.
|
||||
- A configuração do usuário em `agents.defaults.cliBackends.<id>` ainda substitui o padrão do plugin.
|
||||
- A limpeza de configuração específica do backend continua sendo responsabilidade do plugin por meio do hook opcional
|
||||
`normalizeConfig`.
|
||||
- Os Plugins os registram com `api.registerCliBackend(...)`.
|
||||
- O `id` do backend se torna o prefixo do provedor nas referências de modelo.
|
||||
- A configuração do usuário em `agents.defaults.cliBackends.<id>` ainda substitui o padrão do Plugin.
|
||||
- A limpeza de configuração específica do backend continua pertencendo ao Plugin por meio do hook
|
||||
opcional `normalizeConfig`.
|
||||
|
||||
Plugins que precisam de pequenos shims de compatibilidade de prompt/mensagem podem declarar
|
||||
transformações bidirecionais de texto sem substituir um provedor ou backend de CLI:
|
||||
Plugins que precisem de pequenos shims de compatibilidade de prompt/mensagem podem declarar
|
||||
transformações de texto bidirecionais sem substituir um provedor ou backend de CLI:
|
||||
|
||||
```typescript
|
||||
api.registerTextTransforms({
|
||||
@ -303,52 +315,52 @@ api.registerTextTransforms({
|
||||
});
|
||||
```
|
||||
|
||||
`input` reescreve o prompt de sistema e o prompt do usuário passados para a CLI. `output`
|
||||
reescreve deltas em streaming do assistente e o texto final analisado antes que o OpenClaw trate seus
|
||||
próprios marcadores de controle e a entrega por canal.
|
||||
`input` reescreve o prompt de sistema e o prompt do usuário passados à CLI. `output`
|
||||
reescreve deltas transmitidos do assistente e o texto final analisado antes de o OpenClaw processar
|
||||
seus próprios marcadores de controle e a entrega no canal.
|
||||
|
||||
Para CLIs que emitem JSONL compatível com stream-json do Claude Code, defina
|
||||
Para CLIs que emitem JSONL compatível com o stream-json do Claude Code, defina
|
||||
`jsonlDialect: "claude-stream-json"` na configuração desse backend.
|
||||
|
||||
## Overlays MCP de bundle
|
||||
## Overlays MCP empacotados
|
||||
|
||||
Backends de CLI **não** recebem chamadas de ferramenta do OpenClaw diretamente, mas um backend pode
|
||||
optar por um overlay de configuração MCP gerado com `bundleMcp: true`.
|
||||
Os backends de CLI **não** recebem chamadas de ferramenta do OpenClaw diretamente, mas um backend pode
|
||||
optar por uma sobreposição de configuração MCP gerada com `bundleMcp: true`.
|
||||
|
||||
Comportamento integrado atual:
|
||||
Comportamento empacotado atual:
|
||||
|
||||
- `claude-cli`: arquivo de configuração MCP estrito gerado
|
||||
- `codex-cli`: substituições de configuração inline para `mcp_servers`
|
||||
- `google-gemini-cli`: arquivo gerado de configurações de sistema do Gemini
|
||||
|
||||
Quando o bundle MCP está habilitado, o OpenClaw:
|
||||
Quando o MCP empacotado está habilitado, o OpenClaw:
|
||||
|
||||
- inicia um servidor MCP HTTP loopback que expõe ferramentas do Gateway ao processo da CLI
|
||||
- autentica a bridge com um token por sessão (`OPENCLAW_MCP_TOKEN`)
|
||||
- limita o acesso às ferramentas ao contexto atual de sessão, conta e canal
|
||||
- carrega os servidores MCP de bundle habilitados para o espaço de trabalho atual
|
||||
- os mescla com qualquer formato existente de configuração/settings MCP do backend
|
||||
- reescreve a configuração de inicialização usando o modo de integração controlado pelo backend da extensão responsável
|
||||
- inicia um servidor MCP HTTP de loopback que expõe ferramentas do Gateway ao processo da CLI
|
||||
- autentica a ponte com um token por sessão (`OPENCLAW_MCP_TOKEN`)
|
||||
- limita o acesso às ferramentas à sessão, conta e contexto de canal atuais
|
||||
- carrega servidores bundle-MCP habilitados para o workspace atual
|
||||
- mescla isso com qualquer formato existente de configuração/ajustes MCP do backend
|
||||
- reescreve a configuração de inicialização usando o modo de integração pertencente ao backend da extensão proprietária
|
||||
|
||||
Se nenhum servidor MCP estiver habilitado, o OpenClaw ainda injeta uma configuração estrita quando um
|
||||
backend opta por bundle MCP para que execuções em segundo plano permaneçam isoladas.
|
||||
backend opta por MCP empacotado para que execuções em segundo plano permaneçam isoladas.
|
||||
|
||||
## Limitações
|
||||
|
||||
- **Sem chamadas diretas de ferramentas do OpenClaw.** O OpenClaw não injeta chamadas de ferramenta no
|
||||
protocolo do backend de CLI. Backends só veem ferramentas do Gateway quando optam por
|
||||
- **Sem chamadas diretas de ferramenta do OpenClaw.** O OpenClaw não injeta chamadas de ferramenta no
|
||||
protocolo do backend de CLI. Os backends só veem ferramentas do Gateway quando optam por
|
||||
`bundleMcp: true`.
|
||||
- **O streaming é específico do backend.** Alguns backends fazem streaming em JSONL; outros fazem buffer
|
||||
até a saída.
|
||||
- **O streaming é específico do backend.** Alguns backends fazem streaming em JSONL; outros acumulam
|
||||
até encerrar.
|
||||
- **Saídas estruturadas** dependem do formato JSON da CLI.
|
||||
- **Sessões do Codex CLI** são retomadas via saída em texto (sem JSONL), o que é menos
|
||||
- **Sessões do Codex CLI** retomam via saída de texto (sem JSONL), o que é menos
|
||||
estruturado do que a execução inicial com `--json`. As sessões do OpenClaw ainda funcionam
|
||||
normalmente.
|
||||
|
||||
## Solução de problemas
|
||||
|
||||
- **CLI não encontrada**: defina `command` como um caminho completo.
|
||||
- **CLI não encontrada**: defina `command` com um caminho completo.
|
||||
- **Nome de modelo incorreto**: use `modelAliases` para mapear `provider/model` → modelo da CLI.
|
||||
- **Sem continuidade de sessão**: confirme que `sessionArg` está definido e que `sessionMode` não é
|
||||
`none` (o Codex CLI atualmente não consegue retomar com saída JSON).
|
||||
- **Imagens ignoradas**: defina `imageArg` (e confirme que a CLI oferece suporte a caminhos de arquivo).
|
||||
- **Sem continuidade de sessão**: verifique se `sessionArg` está definido e se `sessionMode` não é
|
||||
`none` (atualmente, o Codex CLI não pode retomar com saída JSON).
|
||||
- **Imagens ignoradas**: defina `imageArg` (e verifique se a CLI oferece suporte a caminhos de arquivo).
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
Loading…
Reference in New Issue
Block a user