Referência do harness do Codex

Esta referência aborda a configuração detalhada do plugin oficial codex. Para decisões de configuração e roteamento, comece pelo harness do Codex.

Superfície de configuração do Plugin

Todas as configurações do harness do Codex ficam em plugins.entries.codex.config.

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          discovery: {            enabled: true,            timeoutMs: 2500,          },          appServer: {            mode: "guardian",          },        },      },    },  },}

Campos de nível superior:

Supervisão

Por padrão, a descoberta de sessões nativas lista as sessões não arquivadas do Codex no computador do Gateway e nos nodes pareados que aceitaram participar. Desabilite somente esse catálogo com:

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          sessionCatalog: {            enabled: false,          },        },      },    },  },}

supervision controla separadamente as ferramentas voltadas ao agente:

As entradas de endpoint aceitam estes campos:

A página Sessões do Codex usa o App Server de supervisão do plugin e mostra somente sessões não arquivadas. Sem configurações explícitas de conexão em appServer, essa conexão usa stdio gerenciado no diretório inicial do usuário. As linhas locais armazenadas ou ociosas podem criar um Chat bloqueado ao modelo com histórico limitado do usuário e do assistente até o último turno de origem persistido e concluído. Sua vinculação privada mantém a bifurcação do snapshot, a ramificação canônica de origem appServer, a injeção do histórico e os turnos posteriores nessa conexão. O primeiro início canônico usa o par retornado pela bifurcação. As retomadas posteriores omitem as substituições de modelo e provedor do OpenClaw para que o Codex restaure o par persistido da thread canônica; uma alteração nativa separada pode atualizar esse par, mas o modelo externo e a cadeia de fallback nunca o substituem. As linhas armazenadas e ociosas podem ser arquivadas após a confirmação de que não há outro executor, a menos que outra vinculação ativa do OpenClaw seja proprietária do destino exato ou de um de seus descendentes gerados não arquivados. O OpenClaw segue a paginação de descendentes do Codex e falha de forma fechada em caso de erros de enumeração, ciclos ou esgotamento do limite de segurança. A confirmação ainda abrange clientes nativos desconhecidos e a condição de corrida entre status e arquivamento. Um Chat supervisionado e bloqueado ao modelo não pode ser excluído enquanto protege a vinculação nativa. Origens ativas não podem criar uma ramificação nem ser arquivadas, mas um Chat supervisionado existente ainda pode ser aberto. Todas as linhas de nodes pareados permanecem somente leitura; o transporte do node ainda não fornece o ciclo de vida de streaming necessário ao harness.

appServer.homeScope: "user" por si só altera qual diretório inicial do Codex um processo gerenciado do harness usa; isso não publica o catálogo da frota. Habilitar a supervisão não altera o padrão do harness. Em vez disso, a conexão de supervisão separada usa por padrão o stdio gerenciado no diretório inicial do usuário quando não existem configurações explícitas de conexão em appServer. As configurações explícitas são respeitadas nessa conexão. As vinculações supervisionadas pendentes e confirmadas mantêm essa conexão em todos os turnos; a supervisão desabilitada ou um desvio de conexão/ciclo de vida falha de forma fechada, em vez de recorrer ao harness do diretório inicial do agente. A conexão padrão compartilha as sessões armazenadas com clientes nativos do Codex, mas não o estado de atividade local de seus processos.

As configurações legadas de plugins.entries.codex-supervisor foram descontinuadas. Execute openclaw doctor --fix para migrar a entrada antiga, as definições de endpoint, os sinalizadores de política e as referências de permissão/bloqueio de plugins para este bloco. Em caso de conflito, os valores canônicos explícitos de codex.config.supervision prevalecem.

Transporte do app-server

Para turnos comuns do harness, o OpenClaw inicia o binário gerenciado do Codex fornecido com o plugin oficial (atualmente @openai/codex 0.144.3):

codex app-server --listen stdio://

Isso mantém a versão do app-server vinculada ao plugin oficial codex, em vez de qualquer CLI separada do Codex que esteja instalada localmente. Defina appServer.command somente quando quiser intencionalmente um executável diferente. Turnos gerenciados comuns com o diretório inicial isolado padrão do agente priorizam esse pacote fixado mesmo quando um pacote de aplicativo desktop do macOS está instalado. Quando o Computer Use está habilitado, ou quando homeScope é "user" e consegue carregar o estado nativo do Computer Use, a inicialização gerenciada passa a priorizar o binário do aplicativo desktop que possui as permissões necessárias do macOS. A mesma regra de priorização do desktop se aplica quando a configuração efetiva do Codex de um diretório inicial isolado do agente habilita o Computer Use nativo. Se nenhum pacote de aplicativo desktop estiver instalado, o OpenClaw recorre ao binário do pacote fixado.

A transferência do executável e o isolamento da configuração nativa coordenam clientes dentro de um único processo do Gateway em execução. Reinicie o Gateway depois que outro processo alterar a configuração de plugins nativos do Codex.

A supervisão resolve uma conexão separada. Sem configurações explícitas de conexão em appServer, ela usa stdio gerenciado com homeScope: "user"; o harness comum permanece com stdio gerenciado usando homeScope: "agent". As configurações explícitas de conexão são respeitadas por ambos os caminhos. Defina homeScope: "user" explicitamente quando o harness comum precisar compartilhar $CODEX_HOME (ou ~/.codex) com clientes nativos. Uma vinculação supervisionada privada usa a conexão de supervisão independentemente do padrão do harness comum. Processos independentes do App Server mantêm estados ativos e de aprovação separados.

Para um app-server já em execução, use o transporte WebSocket:

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          appServer: {            transport: "websocket",            url: "ws://gateway-host:39175",            authToken: "${CODEX_APP_SERVER_TOKEN}",            requestTimeoutMs: 60000,          },        },      },    },  },}

Campos de appServer:

appServer.networkProxy é explícito porque altera o contrato de sandbox do Codex. Quando habilitado, o OpenClaw também define features.network_proxy.enabled e default_permissions na configuração da thread do Codex para que o perfil de permissão gerado possa iniciar a rede gerenciada pelo Codex. Por padrão, o OpenClaw gera um nome de perfil openclaw-network-<fingerprint> resistente a colisões com base no corpo do perfil; use profileName somente quando for necessário um nome local estável.

export default {  plugins: {    entries: {      codex: {        config: {          appServer: {            sandbox: "workspace-write",            networkProxy: {              enabled: true,              domains: {                "api.openai.com": "allow",                "blocked.example.com": "deny",              },              allowUpstreamProxy: true,              proxyUrl: "http://127.0.0.1:3128",            },          },        },      },    },  },};

Se o runtime normal do servidor de aplicativos fosse danger-full-access, habilitar networkProxy usaria, em vez disso, acesso ao sistema de arquivos no estilo de workspace para o perfil de permissão gerado. A aplicação de políticas de rede gerenciada pelo Codex é uma rede em sandbox, portanto um perfil de acesso total não protegeria o tráfego de saída.

O Plugin bloqueia handshakes de servidor de aplicativos mais antigos ou sem versão: o servidor de aplicativos do Codex deve informar a versão estável 0.143.0 ou mais recente.

O OpenClaw trata URLs WebSocket de servidor de aplicativos que não sejam de loopback como remotas e exige autenticação WebSocket com identidade por meio de appServer.authToken ou de um cabeçalho Authorization. appServer.authToken e cada valor de appServer.headers.* podem ser um SecretInput; o runtime de segredos resolve SecretRefs e a forma abreviada de variáveis de ambiente antes que o OpenClaw crie as opções de inicialização do servidor de aplicativos, e SecretRefs estruturados não resolvidos causam falha antes que qualquer token ou cabeçalho seja enviado. Quando Plugins nativos do Codex estão configurados, o OpenClaw usa o plano de controle de Plugins do servidor de aplicativos conectado para instalar ou atualizar esses Plugins e, em seguida, atualiza o inventário de aplicativos para que os aplicativos pertencentes aos Plugins fiquem visíveis para a thread do Codex. app/list continua sendo a fonte autoritativa de inventário e metadados, mas a política do OpenClaw decide se thread/start envia config.apps[appId].enabled = true para um aplicativo acessível listado, mesmo que o Codex o marque atualmente como desabilitado. IDs de aplicativos desconhecidos ou ausentes continuam falhando de forma fechada; esse caminho apenas ativa Plugins do marketplace por meio de plugin/install e atualiza o inventário. Conecte o OpenClaw somente a servidores de aplicativos remotos confiáveis para aceitar instalações de Plugins gerenciadas pelo OpenClaw e atualizações do inventário de aplicativos.

Modos de aprovação e sandbox

Por padrão, sessões locais do servidor de aplicativos por stdio usam o modo YOLO: approvalPolicy: "never", approvalsReviewer: "user" e sandbox: "danger-full-access". Essa postura de operador local confiável permite que turnos e heartbeats autônomos do OpenClaw avancem sem prompts de aprovação nativos que ninguém esteja disponível para responder.

Se o arquivo local de requisitos do sistema do Codex não permitir valores implícitos de aprovação YOLO, revisor ou sandbox, o OpenClaw tratará o padrão implícito como guardian e selecionará permissões guardian permitidas. tools.exec.mode: "auto" também força aprovações do Codex revisadas pelo guardian e não preserva substituições legadas inseguras de approvalPolicy: "never" ou sandbox: "danger-full-access"; defina tools.exec.mode: "full" para adotar intencionalmente uma postura sem aprovação. Entradas [[remote_sandbox_config]] correspondentes ao nome do host no mesmo arquivo de requisitos são respeitadas na decisão do padrão de sandbox.

Defina appServer.mode: "guardian" para aprovações do Codex revisadas pelo guardian:

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          appServer: {            mode: "guardian",            serviceTier: "priority",          },        },      },    },  },}

A predefinição guardian se expande para approvalPolicy: "on-request", approvalsReviewer: "auto_review" e sandbox: "workspace-write" quando esses valores são permitidos. Campos individuais de política substituem mode. O valor de revisor mais antigo guardian_subagent ainda é aceito como alias de compatibilidade, mas novas configurações devem usar auto_review.

Quando um sandbox do OpenClaw está ativo, o processo local do servidor de aplicativos do Codex ainda é executado no host do Gateway. Portanto, o OpenClaw desabilita o Code Mode nativo do Codex, servidores MCP do usuário e a execução de Plugins baseada em aplicativos para esse turno, em vez de tratar o sandbox do lado do host do Codex como equivalente ao backend de sandbox do OpenClaw. O acesso ao shell é disponibilizado por meio de ferramentas dinâmicas apoiadas pelo sandbox do OpenClaw, como sandbox_exec e sandbox_process, quando as ferramentas normais de execução/processo estão disponíveis.

Execução nativa em sandbox

O padrão estável é falhar de forma fechada: o sandbox ativo do OpenClaw desabilita superfícies de execução nativa do Codex que, de outra forma, seriam executadas no host do servidor de aplicativos do Codex. Use appServer.experimental.sandboxExecServer: true somente quando quiser testar o suporte a ambientes remotos do Codex com o backend de sandbox do OpenClaw. Esse caminho de prévia funciona com todas as versões compatíveis do servidor de aplicativos do Codex.

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          appServer: {            experimental: {              sandboxExecServer: true,            },          },        },      },    },  },}

Quando a flag está ativada e a sessão atual do OpenClaw está em sandbox, o OpenClaw inicia um servidor de execução de loopback local apoiado pelo sandbox ativo, registra-o no servidor de aplicativos do Codex e inicia a thread e o turno do Codex com esse ambiente pertencente ao OpenClaw. Se o servidor de aplicativos não puder registrar o ambiente, a execução falhará de forma fechada em vez de recorrer silenciosamente à execução no host.

Esse caminho de prévia é somente local. Um servidor de aplicativos WebSocket remoto não pode acessar o servidor de execução de loopback, a menos que esteja sendo executado no mesmo host, portanto o OpenClaw rejeita essa combinação.

Isolamento de autenticação e ambiente

No diretório inicial padrão por agente, a autenticação é selecionada nesta ordem:

1. Um perfil explícito de autenticação do Codex no OpenClaw para o agente.
2. A conta existente do servidor de aplicativos no diretório inicial do Codex desse agente.
3. Somente para inicializações locais do servidor de aplicativos por stdio, CODEX_API_KEY e depois OPENAI_API_KEY, quando nenhuma conta do servidor de aplicativos estiver presente e a autenticação da OpenAI ainda for necessária.

Quando o OpenClaw detecta um perfil de autenticação do Codex no estilo de assinatura do ChatGPT (tipo de credencial OAuth ou token), ele remove CODEX_API_KEY e OPENAI_API_KEY do processo filho do Codex iniciado. Isso mantém as chaves de API no nível do Gateway disponíveis para embeddings ou modelos diretos da OpenAI sem fazer com que turnos nativos do servidor de aplicativos do Codex sejam cobrados pela API acidentalmente.

Perfis explícitos de chave de API do Codex e o fallback de chave por variável de ambiente de stdio local usam o login do servidor de aplicativos em vez de herdar o ambiente do processo filho. Conexões WebSocket do servidor de aplicativos não recebem o fallback de chave de API do ambiente do Gateway; use um perfil de autenticação explícito ou a própria conta do servidor de aplicativos remoto.

Por padrão, inicializações do servidor de aplicativos por stdio herdam o ambiente de processo do OpenClaw. O OpenClaw controla a ponte de conta do servidor de aplicativos do Codex e define CODEX_HOME como um diretório por agente dentro do estado desse agente no OpenClaw. Isso mantém a configuração, as contas, o cache/dados de Plugins e o estado das threads do Codex limitados ao agente do OpenClaw, em vez de vazarem do diretório inicial ~/.codex pessoal do operador.

Defina appServer.homeScope: "user" para compartilhar o estado nativo do Codex com o Codex Desktop e a CLI. Esse modo de diretório inicial do usuário local oferece suporte a stdio gerenciado e transporte Unix explícito. Ele usa $CODEX_HOME quando definido e ~/.codex caso contrário, incluindo autenticação nativa, configuração, Plugins e threads. O OpenClaw ignora sua ponte de perfil de autenticação para o servidor de aplicativos. Turnos verificados do proprietário podem usar codex_threads para listar (com um filtro search opcional), ler, bifurcar, renomear, arquivar e desarquivar essas threads. Bifurque uma thread antes de continuá-la no OpenClaw; processos independentes do Codex não coordenam gravações simultâneas na mesma thread.

Essa adesão por homeScope se aplica a sessões comuns do harness. Um Chat criado por meio de Codex Sessions usa sua conexão de supervisão privada, que preserva a autenticação e a configuração de provedor da conexão nativa para a ramificação canônica e retomadas futuras.

Em um Chat supervisionado bloqueado a um modelo, codex_threads não pode anexar uma bifurcação diferente nem arquivar a thread nativa vinculada ao Chat. A listagem e a leitura somente de metadados permanecem disponíveis. Leituras da transcrição bruta exigem allowRawTranscripts; quando essa opção está desabilitada, a pesquisa na lista também é rejeitada porque a pesquisa nativa pode corresponder a prévias da transcrição. Renomear, desarquivar, criar uma bifurcação separada e arquivar uma thread não relacionada que não pertença a outro Chat do OpenClaw exigem allowWriteControls. Nenhuma das opções ignora uma vinculação bloqueada.

O OpenClaw não reescreve HOME em inicializações locais normais do servidor de aplicativos. Subprocessos executados pelo Codex, como openclaw, gh, git, CLIs de nuvem e comandos de shell, veem o diretório inicial normal do processo e podem encontrar configurações e tokens no diretório inicial do usuário. O Codex também pode descobrir $HOME/.agents/skills e $HOME/.agents/plugins/marketplace.json; essa descoberta de .agents é compartilhada intencionalmente com o diretório inicial do operador e é separada do estado isolado de ~/.codex.

No escopo padrão do agente, os Plugins do OpenClaw e snapshots de Skills do OpenClaw ainda passam pelo registro de Plugins e pelo carregador de Skills do próprio OpenClaw; ativos pessoais ~/.codex do Codex não. Se houver Skills ou Plugins úteis da CLI do Codex em um diretório inicial do Codex que devam fazer parte de um agente isolado do OpenClaw, inventarie-os explicitamente:

openclaw migrate codex --dry-runopenclaw migrate apply codex --yes

Se uma implantação precisar de isolamento adicional do ambiente, adicione essas variáveis a appServer.clearEnv:

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          appServer: {            clearEnv: ["CODEX_API_KEY", "OPENAI_API_KEY"],          },        },      },    },  },}

appServer.clearEnv afeta somente o processo filho iniciado do servidor de aplicativos do Codex. O OpenClaw remove CODEX_HOME e HOME dessa lista durante a normalização da inicialização local: CODEX_HOME continua apontando para o escopo selecionado do agente ou usuário, e HOME continua sendo herdado para que subprocessos possam usar o estado normal do diretório inicial do usuário.

Ferramentas dinâmicas

Por padrão, as ferramentas dinâmicas do Codex usam o carregamento searchable, disponibilizado no namespace openclaw com deferLoading: true. Normalmente, o OpenClaw não disponibiliza ferramentas dinâmicas que dupliquem operações nativas de workspace do Codex ou a própria superfície de pesquisa de ferramentas do Codex:

• read
• write
• edit
• apply_patch
• exec
• process
• update_plan
• tool_call
• tool_describe
• tool_search
• tool_search_code

Quando uma lista finita de permissões do runtime desabilita o Code Mode nativo, o OpenClaw envia uma seleção vazia do ambiente de execução. Nesse caso direto e sem sandbox, o OpenClaw mantém suas ferramentas exec e process filtradas por política como fallback de shell. As listas de permissões do runtime e codexDynamicToolsExclude ainda se aplicam.

A maioria das ferramentas de integração restantes do OpenClaw, como mensagens, mídia, cron, navegador, nodes, gateway, heartbeat_respond e web_search, está disponível por meio da pesquisa de ferramentas do Codex nesse namespace. Isso mantém menor o contexto inicial do modelo. Um pequeno conjunto de ferramentas permanece diretamente invocável independentemente de codexDynamicToolsLoading, porque a pesquisa de ferramentas do Codex pode estar indisponível ou resolver um universo somente de conectores: agents_list, sessions_spawn e sessions_yield. As instruções do desenvolvedor ainda direcionam os subagentes normais do Codex para spawn_agent nativo em trabalhos de subagentes nativos do Codex, enquanto sessions_spawn permanece disponível para delegação explícita do OpenClaw ou ACP. As respostas de origem que usam somente a ferramenta de mensagens também permanecem diretas, pois esse é um contrato de controle de turno.

As ferramentas marcadas como catalogMode: "direct-only", incluindo a ferramenta computer do OpenClaw, são agrupadas em openclaw_direct. O OpenClaw adiciona esse namespace à lista code_mode.direct_only_tool_namespaces do Codex sem substituir as entradas fornecidas pelo operador. Portanto, o Codex expõe essas ferramentas como DirectModelOnly em threads normais e exclusivas do modo de código, em vez de encaminhá-las por meio de chamadas aninhadas de tools.* do Modo de Código. Esse limite é necessário para resultados que contêm imagens: a serialização aninhada do Modo de Código achata a saída de imagem em texto, o que descartaria a captura de tela necessária para a próxima ação no computador.

Defina codexDynamicToolsLoading: "direct" somente ao conectar-se a um servidor de aplicativo personalizado do Codex que não consiga pesquisar ferramentas dinâmicas adiadas ou ao depurar o payload completo das ferramentas.

Tempos limite

As chamadas de ferramentas dinâmicas pertencentes ao OpenClaw são limitadas independentemente de appServer.requestTimeoutMs. Cada solicitação item/tool/call do Codex usa o primeiro tempo limite disponível nesta ordem:

• Um argumento timeoutMs positivo por chamada.
• Para image_generate, agents.defaults.imageGenerationModel.timeoutMs.
• Para image_generate sem um tempo limite configurado, o padrão de 120 segundos para geração de imagens.
• Para a ferramenta de compreensão de mídia image, tools.media.image.timeoutSeconds convertido em milissegundos ou o padrão de mídia de 60 segundos. Para compreensão de imagens, isso se aplica à própria solicitação e não é reduzido pelo trabalho de preparação anterior.
• Para a ferramenta message, um padrão fixo de 120 segundos.
• O padrão de 90 segundos para ferramentas dinâmicas.

Esse watchdog é o orçamento externo do item/tool/call dinâmico. Tempos limite de solicitação específicos do provedor são executados dentro dessa chamada e mantêm sua própria semântica de tempo limite. Os orçamentos de ferramentas dinâmicas são limitados a 600000 ms. Quando o tempo se esgota, o OpenClaw interrompe o sinal da ferramenta quando houver suporte e retorna ao Codex uma resposta de falha da ferramenta dinâmica para que o turno possa continuar, em vez de deixar a sessão em processing.

Depois que o Codex aceita um turno e depois que o OpenClaw responde a uma solicitação do servidor de aplicativo com escopo de turno, o harness espera que o Codex avance no turno atual e, por fim, conclua o turno nativo com turn/completed. Se o servidor de aplicativo ficar inativo por appServer.turnCompletionIdleTimeoutMs, o OpenClaw tenta interromper o turno do Codex, registra um tempo limite de diagnóstico e libera a faixa de sessão do OpenClaw para que mensagens de chat subsequentes não fiquem enfileiradas atrás de um turno nativo obsoleto.

A maioria das notificações não terminais do mesmo turno desativa esse watchdog curto porque o Codex comprovou que o turno ainda está ativo. As transferências de ferramentas usam um orçamento de inatividade pós-ferramenta mais longo: depois que o OpenClaw retorna uma resposta item/tool/call, depois que itens de ferramentas nativas como commandExecution são concluídos, depois de conclusões brutas de custom_tool_call_output e depois do progresso bruto do assistente pós-ferramenta, conclusões brutas de raciocínio ou progresso de raciocínio. A proteção usa appServer.postToolRawAssistantCompletionIdleTimeoutMs quando configurado e usa cinco minutos como padrão caso contrário. Esse mesmo orçamento pós-ferramenta também estende o watchdog de progresso durante a janela silenciosa de síntese antes que o Codex emita o próximo evento do turno atual. Conclusões de raciocínio, conclusões de agentMessage de comentários e progresso bruto de raciocínio ou do assistente antes da ferramenta podem ser seguidos por uma resposta final automática, portanto usam a proteção de resposta pós-progresso em vez de liberar imediatamente a faixa de sessão. Somente itens agentMessage concluídos finais/sem comentários e conclusões brutas do assistente antes da ferramenta ativam a liberação por saída do assistente: se o Codex ficar inativo sem turn/completed, o OpenClaw tenta interromper o turno nativo e libera a faixa de sessão. Falhas reproduzíveis com segurança do servidor de aplicativo stdio, incluindo tempos limite de inatividade na conclusão do turno sem evidências do assistente, de ferramentas, de itens ativos ou de efeitos colaterais, são tentadas novamente uma vez em uma nova tentativa do servidor de aplicativo. Tempos limite inseguros ainda desativam o cliente travado do servidor de aplicativo e liberam a faixa de sessão do OpenClaw. Eles também limpam a associação obsoleta da thread nativa, em vez de serem reproduzidos automaticamente. Tempos limite de monitoramento de conclusão exibem texto de tempo limite específico do Codex: casos reproduzíveis com segurança informam que a resposta pode estar incompleta, enquanto casos inseguros orientam o usuário a verificar o estado atual antes de tentar novamente. Os diagnósticos públicos de tempo limite incluem campos estruturais, como o último método de notificação do servidor de aplicativo, ID/tipo/função do item de resposta bruta do assistente, contagens de solicitações/itens ativos e estado de monitoramento ativado. Quando a última notificação é um item de resposta bruta do assistente, eles também incluem uma prévia limitada do texto do assistente. Eles não incluem conteúdo bruto de prompts ou ferramentas.

Descoberta de modelos

Por padrão, o Plugin do Codex solicita ao servidor de aplicativo os modelos disponíveis. A disponibilidade dos modelos pertence ao servidor de aplicativo do Codex, portanto a lista pode mudar quando o OpenClaw atualiza a versão integrada de @openai/codex ou quando uma implantação direciona appServer.command para um binário diferente do Codex. A disponibilidade também pode ter escopo de conta. Use /codex models em um gateway em execução para ver o catálogo atual desse harness e dessa conta.

Se a descoberta falhar ou exceder o tempo limite, o OpenClaw usará um catálogo alternativo integrado:

Ajuste a descoberta em plugins.entries.codex.config.discovery:

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          discovery: {            enabled: true,            timeoutMs: 2500,          },        },      },    },  },}

Desative a descoberta quando quiser evitar que a inicialização sonde o Codex e usar somente o catálogo alternativo:

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          discovery: {            enabled: false,          },        },      },    },  },}

Arquivos de bootstrap do workspace

O Codex processa AGENTS.md por conta própria por meio da descoberta nativa de documentos do projeto. O OpenClaw não grava arquivos sintéticos de documentos de projeto do Codex nem depende de nomes de arquivos alternativos do Codex para arquivos de persona, pois os nomes alternativos do Codex só se aplicam quando AGENTS.md está ausente.

Para manter a paridade do workspace do OpenClaw, o harness do Codex encaminha os outros arquivos de bootstrap como instruções do desenvolvedor, mas não de forma idêntica:

• TOOLS.md é encaminhado como instruções do desenvolvedor herdadas do Codex, portanto subagentes nativos do Codex iniciados durante o turno também o recebem.
• SOUL.md, IDENTITY.md e USER.md são encaminhados como instruções de colaboração com escopo de turno. Os subagentes nativos do Codex não as herdam, o que evita que os turnos dos subagentes recebam a persona e o perfil de usuário do agente pai.
• A lista compacta de Skills carregadas do OpenClaw também é encaminhada como instruções do desenvolvedor de colaboração com escopo de turno, portanto os subagentes nativos do Codex também não a herdam.
• O conteúdo de HEARTBEAT.md não é injetado; os turnos de Heartbeat recebem um indicador no modo de colaboração para ler o arquivo quando ele existe e não está vazio.
• O conteúdo de MEMORY.md do workspace configurado do agente não é colado na entrada de turno nativa do Codex quando as ferramentas de memória estão disponíveis para esse workspace; quando ele existe, o harness adiciona um pequeno indicador de memória do workspace às instruções do desenvolvedor de colaboração com escopo de turno, e o Codex deve usar memory_search ou memory_get quando a memória persistente for relevante. Se as ferramentas estiverem desativadas, a pesquisa de memória estiver indisponível ou o workspace ativo for diferente do workspace de memória do agente, MEMORY.md usará o caminho normal limitado de contexto do turno.
• BOOTSTRAP.md, quando presente, é encaminhado como contexto de referência da entrada de turno do OpenClaw.

Substituições de ambiente

As substituições de ambiente continuam disponíveis para testes locais:

• OPENCLAW_CODEX_APP_SERVER_BIN
• OPENCLAW_CODEX_APP_SERVER_ARGS
• OPENCLAW_CODEX_APP_SERVER_MODE=yolo|guardian
• OPENCLAW_CODEX_APP_SERVER_APPROVAL_POLICY
• OPENCLAW_CODEX_APP_SERVER_SANDBOX

OPENCLAW_CODEX_APP_SERVER_BIN ignora o binário gerenciado quando appServer.command não está definido.

OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1 foi removido. Use plugins.entries.codex.config.appServer.mode: "guardian" em seu lugar ou OPENCLAW_CODEX_APP_SERVER_MODE=guardian para testes locais pontuais. A configuração é preferível para implantações reproduzíveis porque mantém o comportamento do Plugin no mesmo arquivo revisado que o restante da configuração do harness do Codex.

Relacionados

• Harness do Codex
• Runtime do harness do Codex
• Supervisão do Codex
• Plugins nativos do Codex
• Uso do computador pelo Codex
• Provedor OpenAI
• Referência de configuração