Runtimes de agentes

Um runtime de agente controla um loop de modelo preparado: ele recebe o prompt, conduz a saída do modelo, processa chamadas de ferramentas nativas e retorna o turno concluído ao OpenClaw.

É fácil confundir runtimes com provedores porque ambos aparecem próximos à configuração do modelo. Eles são camadas diferentes:

Um harness é a implementação que fornece um runtime de agente (termo de código). Por exemplo, o harness integrado do Codex implementa o runtime codex. A configuração pública usa agentRuntime.id nas entradas de provedor ou modelo; as chaves de runtime do agente inteiro são legadas e ignoradas. openclaw doctor --fix remove pins antigos de runtime do agente inteiro e reescreve referências legadas de modelos de runtime como referências canônicas de provedor/modelo, além de políticas de runtime no escopo do modelo quando necessário.

Duas famílias de runtime:

• Harnesses incorporados são executados dentro do loop de agente preparado do OpenClaw: o runtime integrado openclaw, além de harnesses de plugins registrados, como codex e copilot.
• Backends de CLI executam um processo de CLI local enquanto mantêm a referência do modelo canônica. Por exemplo, anthropic/claude-opus-4-8 com agentRuntime.id: "claude-cli" no escopo do modelo significa "selecionar o modelo da Anthropic e executar por meio da Claude CLI". claude-cli não é um id de harness incorporado e não deve ser passado para a seleção de AgentHarness.

O harness copilot é um harness de plugin externo separado e opcional para a GitHub Copilot CLI; consulte Runtime de agente do GitHub Copilot para ver a decisão voltada ao usuário entre os runtimes de agente PI, Codex e GitHub Copilot.

Superfícies do Codex

Várias superfícies compartilham o nome Codex:

Essas superfícies são intencionalmente independentes. Ativar o plugin codex disponibiliza os recursos nativos do app-server; openclaw doctor --fix é responsável pelo reparo de rotas legadas do Codex e pela limpeza de pins obsoletos de sessão. Selecionar openai/* para um modelo de agente agora significa "executar isto por meio do Codex", a menos que uma superfície de API da OpenAI que não seja de agente esteja sendo usada.

A configuração comum de assinatura do ChatGPT/Codex usa OAuth do Codex para autenticação, mas mantém a referência do modelo como openai/* e seleciona o runtime codex:

{  agents: {    defaults: {      model: "openai/gpt-5.6-sol",    },  },}

Isso significa que o OpenClaw seleciona uma referência de modelo da OpenAI e, em seguida, solicita que o runtime do app-server do Codex execute o turno de agente incorporado. Não significa "usar cobrança da API", nem que o canal, o catálogo de provedores de modelos ou o armazenamento de sessões do OpenClaw se tornem Codex.

Quando o plugin integrado codex estiver ativado, use a superfície nativa de comandos /codex (/codex bind, /codex threads, /codex resume, /codex steer, /codex stop) para controlar o Codex em linguagem natural, em vez de usar ACP. Use ACP para o Codex somente quando o usuário solicitar explicitamente ACP/acpx ou estiver testando o caminho do adaptador ACP. Claude Code, Gemini CLI, OpenCode, Cursor e harnesses externos semelhantes continuam usando ACP.

Árvore de decisão:

1. Vincular/controlar/thread/retomar/direcionar/interromper no Codex -> superfície nativa de comandos /codex quando o plugin integrado codex estiver ativado.
2. Codex como runtime incorporado ou a experiência normal de agente Codex baseada em assinatura -> openai/<model>.
3. OpenClaw escolhido explicitamente para um modelo da OpenAI -> mantenha a referência do modelo como openai/<model> e defina a política de runtime do provedor/modelo como agentRuntime.id: "openclaw". Um perfil OAuth openai selecionado é roteado internamente pelo transporte de autenticação do Codex do OpenClaw.
4. Referências legadas de modelos Codex na configuração -> repare com openclaw doctor --fix para openai/<model>; o doctor mantém a rota de autenticação do Codex adicionando agentRuntime.id: "codex" no escopo do provedor/modelo quando a referência antiga do modelo implicava isso. Referências legadas de modelos codex-cli/* são reparadas para a mesma rota openai/<model> do app-server do Codex; o OpenClaw não mantém mais um backend integrado da Codex CLI.
5. ACP, acpx ou adaptador ACP do Codex solicitado explicitamente -> runtime: "acp" e agentId: "codex".
6. Claude Code, Gemini CLI, OpenCode, Cursor, Droid ou outro harness externo -> ACP/acpx, não o runtime nativo de subagentes.

Para a divisão de prefixos da família OpenAI, consulte OpenAI e Provedores de modelos. Para o contrato de suporte do runtime Codex, consulte Runtime do harness Codex.

Responsabilidade do runtime

Runtimes diferentes controlam partes diferentes do loop:

Regra de design: se o OpenClaw controla a superfície, ele pode fornecer o comportamento normal de hooks de plugins. Se o runtime nativo controla a superfície, o OpenClaw precisa de eventos de runtime ou hooks nativos. Se o runtime nativo controla o estado canônico da thread, o OpenClaw espelha e projeta o contexto, em vez de reescrever componentes internos sem suporte.

Seleção de runtime

O OpenClaw resolve um runtime incorporado após a resolução do provedor e do modelo, nesta ordem:

1. A política de runtime no escopo do modelo prevalece. Ela fica em uma entrada configurada de modelo do provedor ou em agents.defaults.models["provider/model"].agentRuntime / agents.list[].models["provider/model"].agentRuntime. Um curinga de provedor, como agents.defaults.models["vllm/*"].agentRuntime, é aplicado após a política exata do modelo, permitindo que modelos de provedor descobertos dinamicamente compartilhem um runtime sem substituir exceções exatas por modelo.
2. Política de runtime no escopo do provedor: models.providers.<provider>.agentRuntime.
3. Modo auto: runtimes de plugins registrados podem reivindicar pares de provedor/modelo compatíveis.
4. Se nenhum runtime reivindicar o turno no modo auto, o OpenClaw usa openclaw como runtime de compatibilidade. Use um id de runtime explícito quando a execução precisar ser estrita.

Pins de runtime para a sessão inteira e o agente inteiro são ignorados: OPENCLAW_AGENT_RUNTIME, o estado de sessão agentHarnessId/agentRuntimeOverride, agents.defaults.agentRuntime e agents.list[].agentRuntime. Execute openclaw doctor --fix para remover configurações obsoletas de runtime do agente inteiro e converter referências legadas de modelos de runtime quando for possível preservar a intenção.

Runtimes explícitos de plugins no escopo do provedor/modelo falham de forma restritiva: agentRuntime.id: "codex" em um provedor ou modelo significa Codex ou um erro claro de seleção/runtime — ele nunca é roteado silenciosamente de volta ao OpenClaw. Somente auto pode rotear um turno sem correspondência para o OpenClaw.

Aliases de backends de CLI são diferentes de ids de harnesses incorporados. Forma preferencial para a Claude CLI:

{  agents: {    defaults: {      model: "anthropic/claude-opus-4-8",      models: {        "anthropic/claude-opus-4-8": {          agentRuntime: { id: "claude-cli" },        },      },    },  },}

Referências legadas como claude-cli/claude-opus-4-7 continuam compatíveis, mas novas configurações devem manter o provedor/modelo canônico e colocar o backend de execução na política de runtime do provedor/modelo.

As referências legadas codex-cli/* são diferentes: o doctor as migra para openai/*, para que sejam executadas pelo harness do app-server do Codex, em vez de preservar um backend da Codex CLI.

O modo auto é intencionalmente conservador para a maioria dos provedores. Os modelos de agente da OpenAI são a exceção: tanto um runtime não definido quanto auto são resolvidos para o harness Codex. A configuração explícita do runtime OpenClaw continua sendo uma rota de compatibilidade opcional para turnos de agente openai/*; quando combinada com um perfil OAuth openai selecionado, o OpenClaw roteia esse caminho internamente pelo transporte de autenticação do Codex, mantendo a referência pública do modelo como openai/*. Pins obsoletos de sessão de runtime da OpenAI são ignorados pela seleção de runtime e podem ser removidos com openclaw doctor --fix.

Se openclaw doctor avisar que o plugin codex está ativado enquanto referências legadas de modelos Codex permanecem na configuração, trate isso como estado de rota legada e execute openclaw doctor --fix para reescrevê-las como openai/* com o runtime Codex.

Runtime de agente do GitHub Copilot

O plugin externo @openclaw/copilot registra um runtime copilot opcional baseado na CLI do GitHub Copilot (@github/copilot-sdk). Ele reivindica o provedor canônico de assinatura github-copilot e nunca é selecionado por auto. Ative-o por modelo ou por provedor por meio de agentRuntime.id:

{  agents: {    defaults: {      model: "github-copilot/gpt-5.5",      models: {        "github-copilot/gpt-5.5": {          agentRuntime: { id: "copilot" },        },      },    },  },}

O harness reivindica seu provedor, runtime, chave de sessão da CLI e prefixo do perfil de autenticação em extensions/copilot/doctor-contract-api.ts, que o openclaw doctor carrega automaticamente. Para saber mais sobre configuração, autenticação, espelhamento de transcrições, Compaction, o contrato declarativo do doctor e a decisão mais ampla entre os SDKs do PI, Codex e Copilot, consulte runtime de agente do GitHub Copilot.

Contrato de compatibilidade

Quando um runtime não é do OpenClaw, sua documentação deve declarar quais recursos do OpenClaw ele oferece:

O contrato de suporte do runtime Codex está documentado em runtime do harness Codex.

Rótulos de status

A saída de status pode exibir os rótulos Execution e Runtime. Interprete-os como diagnósticos, não como nomes de provedores:

• Uma referência de modelo como openai/gpt-5.6-sol é o provedor/modelo selecionado.
• Um ID de runtime como codex é o loop que está executando o turno.
• Um rótulo de canal como Telegram ou Discord indica onde a conversa está acontecendo.

Se uma execução mostrar um runtime inesperado, primeiro inspecione a política de runtime do provedor/modelo selecionado. As antigas fixações de runtime da sessão não determinam mais o roteamento.

Relacionados

• Harness Codex
• Runtime do harness Codex
• Runtime de agente do GitHub Copilot
• OpenAI
• Plugins de harness de agente
• Loop do agente
• Modelos
• Status