Ambientes de execução de agentes

Um runtime de agente é o componente que possui um loop de modelo preparado: ele recebe o prompt, conduz a saída do modelo, lida com chamadas de ferramentas nativas e retorna o turno finalizado ao OpenClaw.

Runtimes são fáceis de confundir com provedores porque ambos aparecem perto da configuração de modelo. Eles são camadas diferentes:

Você também verá a palavra harness no código. Um harness é a implementação que fornece um runtime de agente. Por exemplo, o harness Codex incluído implementa o runtime codex. A configuração pública usa agentRuntime.id em entradas de provedor ou modelo; chaves de runtime de agente inteiro são legadas e ignoradas. openclaw doctor --fix remove pins antigos de runtime de agente inteiro e reescreve refs de modelo de runtime legadas para refs canônicas de provedor/modelo mais política de runtime com escopo de modelo quando necessário.

Há duas famílias de runtime:

• Harnesses embutidos são executados dentro do loop de agente preparado do OpenClaw. Hoje, isso é o runtime pi integrado mais harnesses de Plugin registrados, como codex.
• Backends de CLI executam um processo de CLI local mantendo a ref de modelo canônica. Por exemplo, anthropic/claude-opus-4-7 com agentRuntime.id: "claude-cli" com escopo de modelo significa "selecionar o modelo Anthropic, executar por meio da Claude CLI." claude-cli não é um id de harness embutido e não deve ser passado para a seleção de AgentHarness.

Superfícies do Codex

A maior parte da confusão vem de várias superfícies diferentes que compartilham o nome Codex:

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

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

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

Isso significa que o OpenClaw seleciona uma ref de modelo OpenAI e então pede ao runtime do servidor de aplicativo Codex para executar o turno de agente embutido. Isso não significa "usar cobrança por API", e não significa que o canal, o catálogo do provedor de modelos ou o armazenamento de sessão do OpenClaw se tornam Codex.

Quando o Plugin codex incluído está habilitado, o controle do Codex em linguagem natural deve usar a superfície nativa de comando /codex (/codex bind, /codex threads, /codex resume, /codex steer, /codex stop) em vez de ACP. Use ACP para Codex somente quando o usuário pedir explicitamente ACP/acpx ou estiver testando o caminho do adaptador ACP. Claude Code, Gemini CLI, OpenCode, Cursor e harnesses externos semelhantes ainda usam ACP.

Esta é a árvore de decisão voltada ao agente:

1. Se o usuário pedir vincular/controlar/thread/retomar/direcionar/parar Codex, use a superfície nativa de comando /codex quando o Plugin codex incluído estiver habilitado.
2. Se o usuário pedir Codex como o runtime embutido ou quiser a experiência normal de agente Codex respaldada por assinatura, use openai/<model>.
3. Se o usuário escolher explicitamente PI para um modelo OpenAI, mantenha a ref de modelo como openai/<model> e defina a política de runtime de provedor/modelo como agentRuntime.id: "pi". Um perfil de autenticação openai-codex selecionado é roteado internamente pelo transporte legado de autenticação Codex do PI.
4. Se a configuração legada ainda contiver refs de modelo openai-codex/*, repare-a para openai/<model> com openclaw doctor --fix; o doctor mantém a rota de autenticação Codex adicionando agentRuntime.id: "codex" com escopo de provedor/modelo onde a ref de modelo antiga o implicava.
5. Se o usuário disser explicitamente ACP, acpx ou adaptador ACP do Codex, use ACP com runtime: "acp" e agentId: "codex".
6. Se a solicitação for para Claude Code, Gemini CLI, OpenCode, Cursor, Droid ou outro harness externo, use ACP/acpx, não o runtime nativo de subagente.

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

Propriedade do runtime

Runtimes diferentes possuem partes diferentes do loop.

Essa divisão de propriedade é a principal regra de design:

• Se o OpenClaw possui a superfície, o OpenClaw pode fornecer comportamento normal de hooks de Plugin.
• Se o runtime nativo possui a superfície, o OpenClaw precisa de eventos de runtime ou hooks nativos.
• Se o runtime nativo possui o estado canônico da thread, o OpenClaw deve espelhar e projetar contexto, não reescrever internals sem suporte.

Seleção de runtime

O OpenClaw escolhe um runtime embutido após a resolução de provedor e modelo:

1. A política de runtime com escopo de modelo vence. Ela pode existir em uma entrada de modelo de provedor configurada ou em agents.defaults.models["provider/model"].agentRuntime / agents.list[].models["provider/model"].agentRuntime.
2. A política de runtime com escopo de provedor vem em seguida em models.providers.<provider>.agentRuntime.
3. No modo auto, runtimes de Plugin registrados podem reivindicar pares provedor/modelo compatíveis.
4. Se nenhum runtime reivindicar um turno no modo auto, o OpenClaw usa PI como runtime de compatibilidade. Use um id de runtime explícito quando a execução precisar ser estrita.

Pins de runtime de sessão inteira e agente inteiro são ignorados. Isso inclui OPENCLAW_AGENT_RUNTIME, estado de sessão agentHarnessId/agentRuntimeOverride, agents.defaults.agentRuntime e agents.list[].agentRuntime. Execute openclaw doctor --fix para remover configuração obsoleta de runtime de agente inteiro e converter refs de modelo de runtime legadas onde o OpenClaw puder preservar a intenção.

Runtimes de Plugin explícitos de provedor/modelo falham de forma fechada. Por exemplo, agentRuntime.id: "codex" em um provedor ou modelo significa Codex ou um erro claro de seleção/runtime; ele nunca é roteado silenciosamente de volta para PI.

Aliases de backend de CLI são diferentes de ids de harness embutido. A forma preferida da Claude CLI é:

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

Refs legadas como claude-cli/claude-opus-4-7 continuam com suporte para compatibilidade, mas novas configurações devem manter o provedor/modelo canônico e colocar o backend de execução na política de runtime de provedor/modelo.

O modo auto é intencionalmente conservador para a maioria dos provedores. Modelos de agente OpenAI são a exceção: runtime não definido e auto ambos resolvem para o harness Codex. A configuração explícita de runtime PI continua sendo uma rota de compatibilidade opt-in para turnos de agente openai/*; quando pareada com um perfil de autenticação openai-codex selecionado, o OpenClaw roteia o PI internamente pelo transporte legado de autenticação Codex, mantendo a ref de modelo pública como openai/*. Pins de sessão PI OpenAI obsoletos são ignorados pela seleção de runtime e podem ser limpos com openclaw doctor --fix.

Se openclaw doctor avisar que o Plugin codex está habilitado enquanto openai-codex/* permanece na configuração, trate isso como estado de rota legada. Execute openclaw doctor --fix para reescrevê-lo para openai/* com o runtime Codex.

Contrato de compatibilidade

Quando um runtime não é PI, ele deve documentar quais superfícies do OpenClaw ele oferece suporte. Use este formato para docs de runtime:

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

Rótulos de status

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

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

Se uma execução ainda mostrar um runtime inesperado, inspecione primeiro a política de runtime do provedor/modelo selecionado. Fixações de runtime de sessões legadas não decidem mais o roteamento.

Relacionados

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