Harness Codex do OpenClaw: sessões, credenciais e cobrança

O harness do OpenClaw para Codex é o plugin oficial @openclaw/codex: ele entrega uma interação de agente do OpenClaw ao app-server do Codex da OpenAI, para que o Codex controle o loop do modelo, a retomada da thread, a continuação de ferramentas e a compactação. Ele não é um produto de delegação de programação, não é uma camada de cobrança e — o ponto que confunde a maioria das configurações — não é uma forma de executar o Codex em um endpoint de API de terceiros. Qual dessas coisas você realmente precisa é a decisão que esta página existe para ajudar a tomar.

Primeiro, as datas, para que nada aqui fique sem data. O pacote npm openclaw está na versão 2026.9.5 e exige Node >=24.16.0 <25 || >=26.1.0; @openclaw/codex está na versão 2026.9.5, publicado em 18 de setembro de 2026. Ambos foram consultados no registro em 21 de setembro de 2026. Três projetos não relacionados compartilham esses nomes, e nenhum de seus números pertence a este contexto: pjasicek/OpenClaw se descreve como uma reimplementação do jogo de plataforma de 1997 Captain Claw, o pacote npm simples codex é um "gerador de sites estáticos e documentação de código" publicado pela última vez em 2012, e a CLI da OpenAI é @openai/codex (0.155.1 na mesma data).

Cinco superfícies do OpenClaw compartilham o nome "Codex"

A documentação de runtimes de agentes do OpenClaw chama esses componentes de "intencionalmente independentes". Escolher o componente errado é o motivo mais comum para uma configuração parecer correta e não fazer nada.

Um sexto nome não é do OpenClaw. openclaw-code-agent é um plugin de terceiros que executa sessões de programação em segundo plano com aprovação de plano e isolamento de worktree; o próprio README afirma que ele é separado do plugin de runtime acpx incluído no OpenClaw e do plugin core codex incluído. Se você chegou aqui querendo delegação, e não uma troca de runtime, trata-se de um produto diferente, com chaves de configuração diferentes.

Ativando o harness e comprovando que ele está ativo

O caminho documentado consiste em dois comandos — o plugin e depois o login.

openclaw plugins install @openclaw/codex
openclaw models auth login --provider openai

Depois, a configuração mínima. Se você usar uma lista plugins.allow, adicione "codex" a ela também.

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
      },
    },
  },
  agents: {
    defaults: {
      // The docs' own example ref. Legacy codex-cli/* refs are
      // repaired to the same openai/<model> route by doctor --fix.
      model: "openai/gpt-6-astra",
    },
  },
}

Dois detalhes que a documentação do harness deixa explícitos. As alterações na configuração do plugin são aplicadas automaticamente no modo de recarga híbrida, mas um chat existente precisa de /new ou /reset primeiro, para que a próxima interação resolva o harness com base na configuração atual. E o perfil efetivo de ferramentas precisa permitir recursos nativos de shell e sistema de arquivos: coding e full permitem, enquanto messaging e minimal desativam a superfície nativa. Um sandbox comum do OpenClaw ou uma política de ferramentas restrita é uma limitação mais estreita na mesma documentação — ele desativa o modo de código nativo, a menos que você opte pelo caminho experimental do sandbox exec-server — e, quando o sandbox desativa a superfície nativa, os comandos de shell permitidos continuam acessíveis por meio de sandbox_exec.

Requisitos de versão, verificados em 21 de setembro de 2026 contra a referência de transporte do app-server: o plugin gerencia o Codex app-server estável 0.154.0, enquanto executáveis personalizados explícitos, app-servers remotos e binários do macOS Desktop precisam informar uma versão semântica analisável de 0.149.0 ou mais recente. A versão mais recente do npm, @openai/codex, era 0.155.1 no mesmo dia, portanto a versão fixada pelo gerenciamento está um patch atrás — por isso qualquer tutorial que diga "Codex latest" sem uma data fica desatualizado em poucos dias. Migrar uma configuração antiga também é importante: a página de runtimes de agentes diz que o backend de CLI do Codex incluído no OpenClaw foi removido na v2026.5.14, e que referências legadas a codex-cli/* são corrigidas para a mesma rota de app-server do Codex openai/<model> sob openclaw doctor --fix, que gerencia geralmente a correção de rotas legadas do Codex.

Para verificar: uma interação baseada no Codex informa Runtime: OpenAI Codex em /status, e /codex status, /codex models e /codex binding inspecionam o estado do app-server. Um lint — openclaw doctor --lint --only codex/managed-app-server --json — verifica o binário gerenciado, mas a documentação o descreve como somente leitura e coloca um binário selecionado do Codex Desktop, um comando personalizado explícito e um app-server remoto fora dessa verificação do pacote.

Uma tensão que vale conhecer antes de construir sobre isso. A própria documentação do app-server da OpenAI afirma que "o comando app-server e o transporte WebSocket são experimentais e não têm suporte para cargas de trabalho de produção" — observe que o aviso nomeia tanto o comando quanto o transporte. O OpenClaw constrói um recurso distribuído sobre esse comando, e seu campo transport tem como padrão stdio, com websocket usado somente quando você configura um url. As duas afirmações são verdadeiras ao mesmo tempo; decida considerando ambas.

Artefatos de delegação, permissões, cancelamento e retomada

A documentação do harness é honesta sobre os limites do que o status de um subagente nativo comprova: execução, resultado da tarefa e entrega do resultado são fatos distintos; uma thread nativa ociosa, interrompida ou descarregada não comprova que a tarefa foi concluída com sucesso; e, quando a confirmação de encerramento não está disponível, a tarefa solicita que você tente fechar novamente. Subagentes nativos do Codex são o mecanismo próprio do Codex — a delegação explícita do OpenClaw ou do ACP ainda passa por sessions_spawn.

De acordo com a tabela de campos de configuração do plugin, as permissões de execução do app-server iniciado pelo OpenClaw têm como padrão o modo yolo, a política de aprovação never e o sandbox danger-full-access, a menos que os requisitos locais do Codex não permitam essa postura; nesse caso, os padrões do guardian preferem aprovações sob demanda e workspace-write; caso contrário, read-only. requestTimeoutMs, o tempo limite das chamadas do plano de controle do app-server, tem como padrão 60000. Esses são os padrões do OpenClaw para o processo que ele inicia, não os do Codex CLI, e em um repositório desconhecido o primeiro padrão é a configuração a revisar antes da primeira execução.

O controle durante uma interação é nativo: /codex stop, /codex steer, /codex resume, /codex detach, /codex bind, /codex compact, /codex threads, /codex goal, /codex model, /codex fast e /codex permissions. Uma interação restrita é definida por interação, e não por sessão; ela desativa o Code Mode nativo, as seleções de ambiente, os servidores MCP configurados e os relays de hooks nativos somente para essa interação. O contrato de suporte do runtime v1 do OpenClaw também lista como não suportados: a mutação nativa de argumentos de ferramentas (hooks pré-ferramenta podem bloquear, mas o OpenClaw não reescreve os argumentos), um histórico de transcrição nativo do Codex editável, a intervenção na compactação e a captura byte a byte da solicitação à API do modelo — portanto, se sua exigência de auditoria é a solicitação exata enviada, este runtime não pode fornecê-la.

Autorização, direito ao plano e consumo de tokens são três coisas diferentes

Leia a página de política do app-server do Codex do OpenClaw em 21 de setembro de 2026. Há uma armadilha de nomenclatura por cima disso: a página de preços da API da OpenAI afirma que o processamento Priority foi renomeado como modo Fast em 30 de julho de 2026 e que você pode enviar service_tier de "priority" ou "fast", enquanto o appServer.serviceTier do OpenClaw documenta "priority" e "flex" e normaliza um "fast" legado para "priority" — na direção oposta. "Ativar o modo rápido" significa coisas diferentes nos dois sistemas.

Por que um endpoint de terceiros deixa de usar o harness

Este é o único fato que a maioria dos textos de terceiros apresenta ao contrário. A tabela de runtime de agente implícito do OpenClaw, para um runtime de provedor ou modelo que não esteja definido ou seja auto, estabelece o seguinte:

Portanto, apontar o OpenClaw para qualquer URL base de terceiros — incluindo a Kunavo — coloca a interação no runtime integrado do OpenClaw, por design. O prefixo openai/* sozinho nunca seleciona o harness, e forçar agentRuntime.id: "codex" não resolve isso. A página de runtimes afirma que essa configuração "exige um harness do Codex registrado; rotas/autenticações não suportadas falham de forma fechada, exceto que substituições de solicitação definidas pelo autor podem usar o fallback exato de solicitação do OpenClaw declarado pelo Codex antes da execução" — portanto, os dois resultados possíveis são uma interação com falha ou uma interação do OpenClaw, e nenhum deles é o Codex em um endpoint personalizado. Os campos de configuração documentados do plugin também não incluem uma configuração de base URL do modelo; o único campo url ali é o endereço WebSocket ou unix:// do próprio app-server. Não está documentado nem testado se appServer.args poderia inserir uma substituição de provedor no app-server gerenciado; esta página não o apresenta como solução alternativa.

Uma rota do runtime integrado também reformula a solicitação, e a página de provedores personalizados do OpenClaw especifica o escopo de cada regra. Para api: "openai-completions" em um endpoint não nativo — definido como qualquer baseUrl não vazio cujo host não seja api.openai.com — o OpenClaw força compat.supportsDeveloperRole para false e substitui um true explícito. Separadamente, rotas compatíveis com OpenAI no estilo proxy "ignoram a reformulação nativa de solicitações exclusiva da OpenAI": sem service_tier, sem store de Responses, sem store de Completions, sem indicações de cache de prompt, sem a reformulação do payload de compatibilidade de raciocínio da OpenAI e sem cabeçalhos ocultos de atribuição. Sem service_tier no tráfego, o modo Fast e o Flex não podem ser selecionados nessa rota. Em vez disso, essa mesma página oferece passagem de params.extra_body para proxies de Completions compatíveis com OpenAI, headers por provedor e models.providers.<id>.timeoutSeconds para hosts lentos ou remotos.

O próprio Codex é a outra metade da história, e é mais permissivo: a página de configuração avançada do Codex mostra ~/.codex/config.toml com suporte a [model_providers.<id>], usando base_url e env_key. Mas há uma barreira rígida — a referência de configuração afirma que, para model_providers.<id>.wire_api, "responses é o único valor compatível, e é o padrão quando omitido". Portanto, um endpoint que ofereça apenas Chat Completions não pode conduzir o Codex. A mesma página de configuração avançada reserva os IDs integrados openai, ollama e lmstudio, e lista model_provider e model_providers entre as chaves que o Codex ignora em um .codex/config.toml no nível do projeto; portanto, as chaves do provedor pertencem à configuração no nível do usuário. A Kunavo implementa uma superfície nativa de Responses em /v1/responses, o que torna possível a configuração da CLI do Codex — mas isso é a CLI independente do Codex, não o harness do OpenClaw, e a Kunavo não testou nenhum dos dois clientes em runtime.

Quanto custa o software e quanto custam os tokens

O próprio OpenClaw custa $0. Seu índice de documentação descreve o projeto como licenciado sob MIT, conduzido pela comunidade e desenvolvido por uma fundação independente 501(c)(3), com "Nenhum plano pago"; @openclaw/codex é publicado gratuitamente no registro público do npm. Todo custo real é a máquina em que você executa o Gateway, além do uso do modelo, e o uso do modelo chega por meio de um dos três contratos.

Da página de preços do Codex da OpenAI, verificada em 21 de setembro de 2026. Três ressalvas acompanham essa tabela. O cartão de preços publica apenas "A partir de $100" para o Pro; um artigo separado da OpenAI, Sobre os níveis do ChatGPT Pro, nomeia um nível superior de $200, cujas novas inscrições e atualizações estão pausadas desde 10 de setembro de 2026; portanto, confirme no checkout em vez de orçar um número que esta página não viu em um cartão de preços. O uso incluído é publicado apenas como intervalos estimados de mensagens locais por período de cinco horas, não como uma contagem fixa de mensagens. E as tarifas de crédito após os limites incluídos são publicadas em créditos por milhão de tokens, sem valor em dólares para um crédito nessa página de preços — portanto, ela não fornece conversão em dólares para essa linha. Separadamente, o GPT-5.5 será retirado do ChatGPT, do ChatGPT Work e do Codex em todos os planos em 14 de outubro de 2026, enquanto a API da OpenAI não será afetada.

O terceiro contrato é um gateway no runtime integrado do OpenClaw. Considere uma interação delegada que envia 180.000 tokens de entrada não armazenados em cache e recebe 9.000 tokens de saída; as tarifas são preços atuais do catálogo da Kunavo por milhão de tokens.

Estas são operações aritméticas ilustrativas de tokens, não custos medidos de tarefas nem um teto de cobrança — o formato da interação é uma suposição, e uma interação real de agente reenvia o contexto em cada ida e volta de ferramenta. O valor do catálogo da Kunavo é um piso de cobrança, não um limite: quando o upstream informa sua cobrança, a fatura é o maior valor entre o custo do catálogo e o custo do upstream multiplicado pelo markup aplicável. As cobranças de cache e as ferramentas externas ficam fora do exemplo. A recarga mínima é de $10 em crédito pré-pago, que financia um saldo em vez de comprar um plano — consulte os detalhes de cobrança.

A Kunavo não oferece modelo de embeddings, modelo de conversão de texto em fala nem modelo de conversão de fala em texto. Essas etapas não são oferecidas pela Kunavo em nenhuma rota; portanto, encaminhe-as a um provedor que as ofereça.

Essa fronteira é importante aqui porque a tabela de superfícies acima mantém uma rota não relacionada a agentes da OpenAI Platform separada do harness, e uma chave do Gateway cobre apenas os modelos de chat do catálogo da Kunavo.

Qual rota vence quando

Se a resposta for a linha do gateway, comece pela integração da CLI do Codex para entender o formato da API de Responses, compare as opções em a melhor API para o OpenClaw e a melhor API para o Codex e crie uma conta na Kunavo quando estiver pronto para financiar uma chave. Para o lado do orçamento de um assistente auto-hospedado, os preços do OpenClaw separam software, hospedagem e gastos com modelos.

Perguntas frequentes

A tabela de runtimes, a ordem de autenticação, o aviso do app-server, a barreira wire_api, as versões fixadas e os preços dos planos acima foram obtidos em 21 de setembro de 2026 na documentação própria do OpenClaw e da OpenAI, na central de ajuda da OpenAI e nas entradas do registro npm de openclaw, @openclaw/codex, @openai/codex, codex e openclaw-code-agent. Cada afirmação está vinculada à página de origem; quando um documento não resolveu uma questão, o texto informa isso em vez de preencher a lacuna. A Kunavo não executou nenhum teste de runtime do OpenClaw nem do harness do Codex, portanto toda configuração aqui foi verificada contra a documentação de origem, e não demonstrada no endpoint da Kunavo. As tarifas de tokens da Kunavo vêm do catálogo atual, e cada valor em dólares é uma operação aritmética ilustrativa.