Harness do Codex

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Requisitos

• OpenClaw com o Plugin codex incluído disponível.
• Se sua configuração usa plugins.allow, inclua codex.
• App-server Codex 0.125.0 ou mais novo. O Plugin incluído gerencia um binário compatível do app-server Codex por padrão, então comandos codex locais no PATH não afetam a inicialização normal do harness.
• Autenticação Codex disponível por meio de openclaw models auth login --provider openai-codex, uma conta do app-server no diretório inicial Codex do agente ou um perfil explícito de autenticação por chave de API do Codex.

​

Início rápido

openclaw models auth login --provider openai-codex

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
      },
    },
  },
  agents: {
    defaults: {
      model: "openai/gpt-5.5",
    },
  },
}

{
  plugins: {
    allow: ["codex"],
    entries: {
      codex: {
        enabled: true,
      },
    },
  },
}

​

Configuração

{
  auth: {
    order: {
      openai: ["openai-codex:user@example.com", "openai:api-key-backup"],
    },
  },
}

​

Verificar o runtime Codex

Runtime: OpenAI Codex

/codex status
/codex models

​

Roteamento e seleção de modelo

• Use openai/gpt-* para turnos de agente OpenAI pelo Codex.
• Não use openai-codex/gpt-* na configuração. Execute openclaw doctor --fix para reparar refs legadas e pins de rota de sessão obsoletos.
• agentRuntime.id: "codex" é opcional para o modo automático OpenAI normal, mas útil quando uma implantação deve falhar de forma fechada se o Codex estiver indisponível.
• agentRuntime.id: "pi" faz um provedor ou modelo optar pelo comportamento direto do PI quando isso é intencional.
• /codex ... controla conversas nativas do app-server Codex a partir do chat.
• ACP/acpx é um caminho separado de harness externo. Use-o apenas quando o usuário pedir ACP/acpx ou um adaptador de harness externo.

​

Padrões de implantação

​

Implantação básica do Codex

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
      },
    },
  },
  agents: {
    defaults: {
      model: "openai/gpt-5.5",
    },
  },
}

​

Implantação com provedor misto

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
      },
    },
  },
  agents: {
    defaults: {
      model: "anthropic/claude-opus-4-6",
    },
    list: [
      {
        id: "main",
        default: true,
        model: "anthropic/claude-opus-4-6",
      },
      {
        id: "codex",
        name: "Codex",
        model: "openai/gpt-5.5",
      },
    ],
  },
}

​

Implantação Codex fail-closed

{
  models: {
    providers: {
      openai: {
        agentRuntime: {
          id: "codex",
        },
      },
    },
  },
  agents: {
    defaults: {
      model: "openai/gpt-5.5",
    },
  },
  plugins: {
    entries: {
      codex: {
        enabled: true,
      },
    },
  },
}

​

Política do app-server

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

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

​

Comandos e diagnósticos

• /codex status verifica a conectividade do app-server, modelos, conta, limites de taxa, servidores MCP e Skills.
• /codex models lista modelos ativos do app-server do Codex.
• /codex threads [filter] lista threads recentes do app-server do Codex.
• /codex resume <thread-id> anexa a sessão atual do OpenClaw a uma thread existente do Codex.
• /codex compact pede ao app-server do Codex para compactar a thread anexada.
• /codex review inicia a revisão nativa do Codex para a thread anexada.
• /codex diagnostics [note] pergunta antes de enviar feedback do Codex para a thread anexada.
• /codex account mostra o status da conta e dos limites de taxa.
• /codex mcp lista o status dos servidores MCP do app-server do Codex.
• /codex skills lista as Skills do app-server do Codex.

​

Inspecionar threads do Codex localmente

codex resume <thread-id>

1. Perfis de autenticação OpenAI ordenados para o agente, preferencialmente em auth.order.openai. IDs de perfil openai-codex:* existentes continuam válidos.
2. A conta existente do app-server no Codex home desse agente.
3. Apenas para inicializações locais stdio do app-server, CODEX_API_KEY, depois OPENAI_API_KEY, quando nenhuma conta de app-server está presente e a autenticação OpenAI ainda é necessária.

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

• 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

​

Plugins nativos do Codex

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          codexPlugins: {
            enabled: true,
            allow_destructive_actions: true,
            plugins: {
              "google-calendar": {
                enabled: true,
                marketplaceName: "openai-curated",
                pluginName: "google-calendar",
              },
            },
          },
        },
      },
    },
  },
}

​

Uso do computador

​

Limites de runtime

• Ferramentas dinâmicas do OpenClaw têm suporte. O Codex pede ao OpenClaw para executar essas ferramentas, então o OpenClaw permanece no caminho de execução.
• Shell, patch, MCP e ferramentas nativas de app nativos do Codex pertencem ao Codex. O OpenClaw pode observar ou bloquear eventos nativos selecionados por meio do relay compatível, mas não reescreve argumentos de ferramentas nativas.
• O Codex é responsável pela compaction nativa. O OpenClaw mantém um espelho de transcrição para histórico de canais, pesquisa, /new, /reset e futuras trocas de modelo ou harness.
• Geração de mídia, entendimento de mídia, TTS, aprovações e saída de ferramentas de mensagens continuam pelas configurações correspondentes de provedor/modelo do OpenClaw.
• tool_result_persist se aplica a resultados de ferramenta de transcrição pertencentes ao OpenClaw, não a registros de resultados de ferramentas nativas do Codex.

​

Solução de problemas

​

Relacionados

• Referência do harness do Codex
• Runtime do harness do Codex
• Plugins nativos do Codex
• Uso do Computador do Codex
• Runtimes de agente
• Provedores de modelo
• Provedor OpenAI
• Plugins de harness de agente
• Hooks de plugin
• Exportação de diagnósticos
• Status
• Testes