codex incluído apenas prepara o app-server do Codex:
ele habilita o suporte a Plugins do Codex, encontra ou instala o Plugin Codex
Computer Use configurado, verifica se o servidor MCP computer-use está disponível e
então deixa o Codex controlar as chamadas nativas de ferramenta MCP durante turnos em modo Codex.
Use esta página quando o OpenClaw já estiver usando o harness nativo do Codex. Para a
configuração do runtime em si, consulte harness do Codex.
OpenClaw.app e Peekaboo
A integração Peekaboo do OpenClaw.app é separada do Codex Computer Use. O aplicativo macOS pode hospedar um soquete PeekabooBridge para que a CLIpeekaboo possa reutilizar as
permissões locais de Acessibilidade e Gravação de Tela do aplicativo para as próprias
ferramentas de automação do Peekaboo. Essa ponte não instala nem faz proxy do Codex Computer Use, e
o Codex Computer Use não chama através do soquete PeekabooBridge.
Use ponte Peekaboo quando quiser que o OpenClaw.app seja
um host ciente de permissões para automação da CLI Peekaboo. Use esta página quando um
agente OpenClaw em modo Codex precisar ter o Plugin MCP computer-use nativo do Codex
disponível antes do início do turno.
Aplicativo iOS
O aplicativo iOS é separado do Codex Computer Use. Ele não instala nem faz proxy do servidor MCPcomputer-use do Codex e não é um backend de controle de desktop.
Em vez disso, o aplicativo iOS se conecta como um nó do OpenClaw e expõe
capacidades móveis por meio de comandos de nó como canvas.*, camera.*, screen.*,
location.* e talk.*.
Use iOS quando quiser que um agente controle um nó iPhone pelo
Gateway. Use esta página quando um agente em modo Codex precisar controlar o desktop
macOS local pelo Plugin Computer Use nativo do Codex.
MCP direto do cua-driver
Codex Computer Use não é a única forma de expor controle de desktop. Se você quiser que runtimes gerenciados pelo OpenClaw chamem o driver da TryCua diretamente, use o servidor upstreamcua-driver mcp pelo registro MCP do OpenClaw em vez do fluxo de marketplace
específico do Codex.
Depois de instalar cua-driver, peça a ele o comando do OpenClaw:
cua-driver, não concede essas permissões nem contorna o modelo de segurança
do driver upstream.
Configuração rápida
Definaplugins.entries.codex.config.computerUse quando turnos em modo Codex precisarem ter
Computer Use disponível antes de uma conversa começar. autoInstall: true opta pelo
Computer Use e permite que o OpenClaw o instale ou reabilite antes do turno:
/Applications/Codex.app/Contents/Resources/plugins/openai-bundled antes de
falhar. Se a configuração ainda não conseguir tornar o servidor MCP disponível, o turno falha
antes que a conversa comece.
Depois de alterar a configuração do Computer Use, use /new ou /reset no chat afetado
antes de testar, se uma conversa existente do Codex já tiver começado.
Na inicialização stdio gerenciada no macOS, o OpenClaw prefere o pacote assinado do aplicativo Codex
de desktop em /Applications/Codex.app/Contents/Resources/codex quando ele existe.
Isso mantém o Computer Use sob o pacote do aplicativo que controla as permissões locais
de controle de desktop. Se o aplicativo de desktop não estiver instalado, o OpenClaw recorre ao
binário gerenciado do Codex instalado junto ao Plugin. Se um aplicativo de desktop instalado
inicializar com uma versão de app-server incompatível, o OpenClaw fecha esse processo filho
e tenta o próximo candidato a binário gerenciado, em vez de deixar um aplicativo de desktop
obsoleto ofuscar o fallback local do Plugin. A configuração explícita appServer.command
ou OPENCLAW_CODEX_APP_SERVER_BIN ainda substitui essa seleção gerenciada.
Comandos
Use os comandos/codex computer-use a partir de qualquer superfície de chat onde a superfície de comandos do Plugin codex
esteja disponível. Estes são comandos de chat/runtime do OpenClaw,
não subcomandos da CLI openclaw codex ...:
status é somente leitura. Ele não adiciona origens de marketplace, instala Plugins nem
habilita suporte a Plugins do Codex. Se nenhuma configuração optar pelo Computer Use, status pode
relatar desabilitado mesmo após um comando de instalação avulso.
install habilita o suporte a Plugins no app-server do Codex, opcionalmente adiciona uma
origem de marketplace configurada, instala ou reabilita o Plugin configurado pelo app-server
do Codex, recarrega servidores MCP e verifica se o servidor MCP expõe ferramentas.
Como a instalação altera recursos confiáveis do host, somente um proprietário ou um cliente
Gateway operator.admin pode executar install. Outros remetentes autorizados podem
continuar usando o comando status somente leitura, inclusive com substituições.
Opções de marketplace
O OpenClaw usa a mesma API de app-server que o próprio Codex expõe. Os campos de marketplace escolhem onde o Codex deve encontrarcomputer-use.
| Campo | Use quando | Suporte à instalação |
|---|---|---|
| Nenhum campo de marketplace | Você quer que o app-server do Codex use marketplaces que ele já conhece. | Sim, quando o app-server retorna um marketplace local. |
marketplaceSource | Você tem uma origem de marketplace do Codex que o app-server pode adicionar. | Sim, para /codex computer-use install explícito. |
marketplacePath | Você já sabe o caminho de arquivo do marketplace local no host. | Sim, para instalação explícita e instalação automática no início do turno. |
marketplaceName | Você quer selecionar um marketplace já registrado pelo nome. | Sim somente quando o marketplace selecionado tem um caminho local. |
plugin/list por até
marketplaceDiscoveryTimeoutMs milissegundos. O padrão é 60 segundos.
Se vários marketplaces conhecidos contiverem Computer Use, o OpenClaw prefere
openai-bundled, depois openai-curated, depois local. Correspondências ambíguas desconhecidas
falham de forma fechada e pedem que você defina marketplaceName ou marketplacePath.
Marketplace macOS incluído
Builds recentes do desktop Codex incluem Computer Use aqui:computerUse.autoInstall é true e nenhum marketplace contendo
computer-use está registrado, o OpenClaw tenta adicionar automaticamente a raiz padrão
do marketplace incluído:
/codex computer-use install --source <marketplace-root> uma vez ou defina computerUse.marketplacePath como um
caminho de arquivo de marketplace local. Use --marketplace-path somente quando tiver o
caminho do arquivo JSON do marketplace, não a raiz do marketplace incluído.
Limite do catálogo remoto
O app-server do Codex pode listar e ler entradas de catálogo somente remotas, mas atualmente não oferece suporte aplugin/install remoto. Isso significa que marketplaceName pode
selecionar um marketplace somente remoto para verificações de status, mas instalações e reabilitações
ainda precisam de um marketplace local via marketplaceSource ou marketplacePath.
Se o status disser que o Plugin está disponível em um marketplace remoto do Codex, mas a
instalação remota não for compatível, execute a instalação com uma origem ou caminho local:
Referência de configuração
| Campo | Padrão | Significado |
|---|---|---|
enabled | inferido | Exige Computer Use. O padrão é true quando outro campo de Computer Use está definido. |
autoInstall | false | Instala ou reabilita a partir de marketplaces já descobertos no início do turno. |
marketplaceDiscoveryTimeoutMs | 60000 | Por quanto tempo a instalação aguarda a descoberta de marketplace pelo app-server do Codex. |
marketplaceSource | não definido | String de origem passada para marketplace/add do app-server do Codex. |
marketplacePath | não definido | Caminho de arquivo de marketplace local do Codex que contém o Plugin. |
marketplaceName | não definido | Nome do marketplace registrado do Codex a selecionar. |
pluginName | computer-use | Nome do Plugin no marketplace do Codex. |
mcpServerName | computer-use | Nome do servidor MCP exposto pelo Plugin instalado. |
marketplaceSource.
Adicionar uma nova origem é uma operação de configuração explícita, portanto use
/codex computer-use install --source <marketplace-source> uma vez, depois deixe
autoInstall lidar com futuras reabilitações a partir de marketplaces locais descobertos.
A instalação automática no início do turno pode usar um marketplacePath configurado, porque ele já é
um caminho local no host.
O que o OpenClaw verifica
O OpenClaw relata internamente um motivo de configuração estável e formata o status voltado ao usuário para o chat:| Motivo | Significado | Próxima etapa |
|---|---|---|
disabled | computerUse.enabled foi resolvido como false. | Defina enabled ou outro campo de Computer Use. |
marketplace_missing | Nenhum marketplace correspondente estava disponível. | Configure origem, caminho ou nome do marketplace. |
plugin_not_installed | O marketplace existe, mas o plugin não está instalado. | Execute a instalação ou habilite autoInstall. |
plugin_disabled | O Plugin está instalado, mas desabilitado na configuração do Codex. | Execute a instalação para reabilitá-lo. |
remote_install_unsupported | O marketplace selecionado é somente remoto. | Use marketplaceSource ou marketplacePath. |
mcp_missing | O Plugin está habilitado, mas o servidor MCP está indisponível. | Verifique o Codex Computer Use e as permissões do SO. |
ready | O Plugin e as ferramentas MCP estão disponíveis. | Inicie a rodada em modo Codex. |
check_failed | Uma solicitação ao app-server do Codex falhou durante a verificação de status. | Verifique a conectividade e os logs do app-server. |
auto_install_blocked | A configuração no início da rodada precisaria adicionar uma nova origem. | Execute a instalação explícita primeiro. |
Permissões do macOS
Computer Use é específico do macOS. O servidor MCP pertencente ao Codex pode precisar de permissões locais do SO antes de conseguir inspecionar ou controlar aplicativos. Se o OpenClaw disser que Computer Use está instalado, mas o servidor MCP está indisponível, verifique primeiro a configuração de Computer Use no lado do Codex:- O app-server do Codex está em execução no mesmo host em que o controle da área de trabalho deve acontecer.
- O Plugin Computer Use está habilitado na configuração do Codex.
- O servidor MCP
computer-useaparece no status de MCP do app-server do Codex. - O macOS concedeu as permissões exigidas para o aplicativo de controle da área de trabalho.
- A sessão atual do host consegue acessar a área de trabalho sendo controlada.
computerUse.enabled é true. Uma
rodada em modo Codex não deve prosseguir silenciosamente sem as ferramentas nativas de área de trabalho
que a configuração exigiu.
Solução de problemas
O status diz que não está instalado. Execute/codex computer-use install. Se o
marketplace não for descoberto, passe --source ou --marketplace-path.
O status diz que está instalado, mas desabilitado. Execute /codex computer-use install novamente.
A instalação pelo app-server do Codex grava a configuração do plugin de volta como habilitada.
O status diz que instalação remota não é compatível. Use uma origem ou
caminho de marketplace local. Entradas de catálogo somente remotas podem ser inspecionadas, mas não instaladas por meio da
API atual do app-server.
O status diz que o servidor MCP está indisponível. Execute a instalação novamente uma vez para que os servidores MCP
sejam recarregados. Se ele continuar indisponível, corrija o aplicativo Codex Computer Use,
o status de MCP do app-server do Codex ou as permissões do macOS.
O status ou uma sondagem expira em computer-use.list_apps. O Plugin e o servidor MCP
estão presentes, mas a ponte local do Computer Use não respondeu. Encerre ou
reinicie o Codex Computer Use, reinicie o Codex Desktop se necessário e tente novamente em uma
sessão nova do OpenClaw. Se o host anteriormente executou Computer Use por meio de um app-server do Codex gerenciado
mais antigo, atualize o plugin instalado a partir do marketplace empacotado no desktop:
Native hook relay unavailable. O hook de ferramenta nativo do Codex
não conseguiu alcançar um relay ativo do OpenClaw pela ponte local ou pelo fallback do
Gateway. Inicie uma sessão nova do OpenClaw com /new ou /reset. Se funcionar
uma vez e depois falhar novamente em uma chamada de ferramenta posterior, /new está apenas limpando a
tentativa atual; reinicie o app-server do Codex ou o Gateway do OpenClaw para que threads
antigas e registros de hook sejam descartados, e então tente novamente em uma sessão nova.
A instalação automática no início da rodada recusa uma origem. Isso é intencional. Adicione a
origem com /codex computer-use install --source <marketplace-source> explícito
primeiro; então, futuras instalações automáticas no início da rodada poderão usar o
marketplace local descoberto.