diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json index 55115d281..9b629775f 100644 --- a/.openclaw-sync/source.json +++ b/.openclaw-sync/source.json @@ -1,5 +1,5 @@ { "repository": "openclaw/openclaw", - "sha": "802f13ac15063c23c98983c0096f8f00168d91dd", - "syncedAt": "2026-04-27T23:35:23.935Z" + "sha": "697d85aefeb4df2bd97a1a3d64235f41d61f3dca", + "syncedAt": "2026-04-27T23:37:20.130Z" } diff --git a/docs/plugins/codex-computer-use.md b/docs/plugins/codex-computer-use.md index b119eebbb..24df3bc14 100644 --- a/docs/plugins/codex-computer-use.md +++ b/docs/plugins/codex-computer-use.md @@ -39,8 +39,9 @@ Computer Use available before a thread starts: agents: { defaults: { model: "openai/gpt-5.5", - embeddedHarness: { - runtime: "codex", + agentRuntime: { + id: "codex", + fallback: "none", }, }, }, @@ -50,13 +51,22 @@ Computer Use available before a thread starts: With this config, OpenClaw checks Codex app-server before each Codex-mode turn. If Computer Use is missing but Codex app-server has already discovered an installable marketplace, OpenClaw asks Codex app-server to install or re-enable -the plugin and reload MCP servers. If setup still cannot make the MCP server -available, the turn fails before the thread starts. +the plugin and reload MCP servers. On macOS, when no matching marketplace is +registered and the standard Codex app bundle exists, OpenClaw also tries to +register the bundled Codex marketplace from +`/Applications/Codex.app/Contents/Resources/plugins/openai-bundled` before it +fails. If setup still cannot make the MCP server available, the turn fails +before the thread starts. + +Existing sessions keep their runtime and Codex thread binding. After changing +`agentRuntime` or Computer Use config, use `/new` or `/reset` in the affected +chat before testing. ## Commands Use the `/codex computer-use` commands from any chat surface where the `codex` -plugin command surface is available: +plugin command surface is available. These are OpenClaw chat/runtime commands, +not `openclaw codex ...` CLI subcommands: ```text /codex computer-use status @@ -93,6 +103,32 @@ If multiple known marketplaces contain Computer Use, OpenClaw prefers `openai-bundled`, then `openai-curated`, then `local`. Unknown ambiguous matches fail closed and ask you to set `marketplaceName` or `marketplacePath`. +## Bundled macOS marketplace + +Recent Codex desktop builds bundle Computer Use here: + +```text +/Applications/Codex.app/Contents/Resources/plugins/openai-bundled/plugins/computer-use +``` + +When `computerUse.autoInstall` is true and no marketplace containing +`computer-use` is registered, OpenClaw tries to add the standard bundled +marketplace root automatically: + +```text +/Applications/Codex.app/Contents/Resources/plugins/openai-bundled +``` + +You can also register it explicitly from a shell with Codex: + +```bash +codex plugin marketplace add /Applications/Codex.app/Contents/Resources/plugins/openai-bundled +``` + +If you use a nonstandard Codex app path, set `computerUse.marketplacePath` to a +local marketplace file path or run `/codex computer-use install --source +` once. + ## Remote catalog limit Codex app-server can list and read remote-only catalog entries, but it does not @@ -125,6 +161,8 @@ Turn-start auto-install intentionally refuses configured `marketplaceSource` values. Adding a new source is an explicit setup operation, so use `/codex computer-use install --source ` once, then let `autoInstall` handle future re-enables from discovered local marketplaces. +Turn-start auto-install can use a configured `marketplacePath`, because that is +already a local path on the host. ## What OpenClaw checks @@ -180,6 +218,17 @@ current app-server API. servers reload. If it remains unavailable, fix the Codex Computer Use app, Codex app-server MCP status, or macOS permissions. +**Status or a probe times out on `computer-use.list_apps`.** The plugin and MCP +server are present, but the local Computer Use bridge did not answer. Quit or +restart Codex Computer Use, relaunch Codex Desktop if needed, then retry in a +fresh OpenClaw session. + +**A Computer Use tool says `Native hook relay unavailable`.** The Codex-native +tool hook reached OpenClaw with a stale or missing relay registration. Start a +fresh OpenClaw session with `/new` or `/reset`. If it keeps happening, restart +the gateway so old app-server threads and hook registrations are dropped, then +retry. + **Turn-start auto-install refuses a source.** This is intentional. Add the source with explicit `/codex computer-use install --source ` first, then future turn-start auto-install can use the discovered local diff --git a/docs/plugins/codex-harness.md b/docs/plugins/codex-harness.md index 022eccc16..ed8eb98fb 100644 --- a/docs/plugins/codex-harness.md +++ b/docs/plugins/codex-harness.md @@ -571,8 +571,9 @@ Minimal config: agents: { defaults: { model: "openai/gpt-5.5", - embeddedHarness: { - runtime: "codex", + agentRuntime: { + id: "codex", + fallback: "none", }, }, }, @@ -593,6 +594,13 @@ silently running without the native Computer Use tools. See [Codex Computer Use](/plugins/codex-computer-use) for marketplace choices, remote catalog limits, status reasons, and troubleshooting. +When `computerUse.autoInstall` is true, OpenClaw can register the standard +bundled Codex Desktop marketplace from +`/Applications/Codex.app/Contents/Resources/plugins/openai-bundled` if Codex +has not discovered a local marketplace yet. Use `/new` or `/reset` after +changing runtime or Computer Use config so existing sessions do not keep an old +PI or Codex thread binding. + ## Common recipes Local Codex with default stdio transport: @@ -853,6 +861,12 @@ and that the remote app-server speaks the same Codex app-server protocol version provider path in `auto` mode. If you force `agentRuntime.id: "codex"`, every embedded turn for that agent must be a Codex-supported OpenAI model. +**Computer Use is installed but tools do not run:** check +`/codex computer-use status` from a fresh session. If a tool reports +`Native hook relay unavailable`, use `/new` or `/reset`; if it persists, restart +the gateway to clear stale native hook registrations. If `computer-use.list_apps` +times out, restart Codex Computer Use or Codex Desktop and retry. + ## Related - [Agent harness plugins](/plugins/sdk-agent-harness)