Codex harness

Documentation Index

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

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

​

Quick config

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,
      },
    },
  },
}

​

What this plugin changes

• replace direct OpenAI API-key surfaces such as images, embeddings, speech, or realtime
• convert openai-codex/* model refs without openclaw doctor --fix
• make ACP/acpx the default Codex path
• use stale whole-agent or session runtime pins for routing
• replace OpenClaw channel delivery, session files, auth-profile storage, or message routing

• before_prompt_build
• before_compaction, after_compaction
• llm_input, llm_output
• before_tool_call, after_tool_call
• before_message_write for mirrored transcript records
• before_agent_finalize through Codex Stop relay
• agent_end

​

Route map

• openai-codex/* is a legacy route that doctor rewrites.
• Provider/model agentRuntime.id: "codex" requires the Codex harness and fails closed if it is unavailable.
• Provider/model agentRuntime.id: "auto" lets registered harnesses claim matching provider routes; OpenAI agent refs resolve to Codex instead of PI.
• /codex ... answers “which native Codex conversation should this chat bind or control?”
• ACP answers “which external harness process should acpx launch?”

​

Pick the right model prefix

​

What doctor warnings mean

​

Requirements

• OpenClaw with the bundled codex plugin available.
• Codex app-server 0.125.0 or newer. The bundled plugin manages a compatible Codex app-server binary by default, so local codex commands on PATH do not affect normal harness startup.
• Codex auth available to the app-server process or to OpenClaw’s Codex auth bridge. Local app-server launches use an OpenClaw-managed Codex home for each agent and an isolated child HOME, so they do not read your personal ~/.codex account, skills, plugins, config, thread state, or native $HOME/.agents/skills by default.

​

Workspace bootstrap files

​

Add Codex alongside other models

• Use openai/gpt-* for OpenAI agent turns; Codex is selected by default.
• Put runtime overrides on models.providers.<provider>.agentRuntime or on a model entry such as agents.defaults.models["anthropic/claude-opus-4-7"].agentRuntime.
• Use legacy codex/* refs only for compatibility. New configs should prefer openai/*; add an explicit Codex runtime policy only when you need to make the provider/model rule strict.

{
  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",
      },
    ],
  },
}

• The default main agent uses the normal provider path and PI compatibility fallback.
• The codex agent uses the Codex app-server harness.
• If Codex is missing or unsupported for the codex agent, the turn fails instead of quietly using PI.

​

Agent command routing

​

Codex-only deployments

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

​

Per-agent Codex

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

​

Model discovery

• GPT-5.5
• GPT-5.4 mini
• GPT-5.2

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

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

​

App-server connection and policy

codex app-server --listen stdio://

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

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

openclaw migrate codex --dry-run
openclaw migrate apply codex --yes

1. An explicit OpenClaw Codex auth profile for the agent.
2. The app-server’s existing account in that agent’s Codex home.
3. For local stdio app-server launches only, CODEX_API_KEY, then OPENAI_API_KEY, when no app-server account is present and OpenAI auth is still required.

{
  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

​

Native Codex plugins

• Only openai-curated plugins that were already installed in the source Codex app-server inventory are migration-eligible.
• Migration writes explicit plugin identities with marketplaceName and pluginName; it does not write local marketplacePath cache paths.
• codexPlugins.enabled is the global enablement switch. There is no plugins["*"] wildcard and no config key that grants arbitrary install authority.
• Unsupported marketplaces, cached plugin bundles, hooks, and Codex config files are preserved in the migration report for manual review.

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

• Global allow_destructive_actions defaults to false.
• Per-plugin allow_destructive_actions overrides the global policy for that plugin.
• When policy is false, OpenClaw returns a deterministic decline.
• When policy is true, OpenClaw auto-accepts only safe schemas it can map to an approval response, such as a boolean approve field.
• Missing plugin identity, ambiguous ownership, a missing turn id, a wrong turn id, or an unsafe elicitation schema declines instead of prompting.

• auth_required: migration installed the plugin but one of its apps still needs authentication. The explicit plugin entry is written disabled until you reauthorize and enable it.
• marketplace_missing or plugin_missing: the target Codex app-server cannot see the expected openai-curated marketplace or plugin.
• app_inventory_missing or app_inventory_stale: app readiness came from an empty or stale cache; OpenClaw schedules an async refresh and excludes plugin apps until ownership/readiness is known.
• app_ownership_ambiguous: app inventory only matched by display name, so the app is not exposed to the Codex thread.

​

Computer use

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

• /codex computer-use status
• /codex computer-use install
• /codex computer-use install --source <marketplace-source>
• /codex computer-use install --marketplace-path <path>

​

Common recipes

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
      },
    },
  },
}

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

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          appServer: {
            mode: "guardian",
            approvalPolicy: "on-request",
            approvalsReviewer: "auto_review",
            sandbox: "workspace-write",
          },
        },
      },
    },
  },
}

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          appServer: {
            transport: "websocket",
            url: "ws://gateway-host:39175",
            headers: {
              "X-OpenClaw-Agent": "main",
            },
          },
        },
      },
    },
  },
}

​

Codex command

• /codex status shows live app-server connectivity, models, account, rate limits, MCP servers, and skills.
• /codex models lists live Codex app-server models.
• /codex threads [filter] lists recent Codex threads.
• /codex resume <thread-id> attaches the current OpenClaw session to an existing Codex thread.
• /codex compact asks Codex app-server to compact the attached thread.
• /codex review starts Codex native review for the attached thread.
• /codex diagnostics [note] asks before sending Codex diagnostics feedback for the attached thread.
• /codex computer-use status checks the configured Computer Use plugin and MCP server.
• /codex computer-use install installs the configured Computer Use plugin and reloads MCP servers.
• /codex account shows account and rate-limit status.
• /codex mcp lists Codex app-server MCP server status.
• /codex skills lists Codex app-server skills.

​

Common debugging workflow

1. Run /diagnostics bad tool choice after image upload or another short note that describes what you saw.
2. Approve the diagnostics request once. The approval creates the local Gateway diagnostics zip and, because the session is using the Codex harness, also sends the relevant Codex feedback bundle to OpenAI servers.
3. Copy the completed diagnostics reply into the bug report or support thread. It includes the local bundle path, privacy summary, OpenClaw session ids, Codex thread ids, and an Inspect locally line for each Codex thread.
4. If you want to debug the run yourself, run the printed Inspect locally command in a terminal. It looks like codex resume <thread-id> and opens the native Codex thread so you can inspect the conversation, continue it locally, or ask Codex why it chose a particular tool or plan.

​

Inspect a Codex thread from the CLI

codex resume <thread-id>

​

Hook boundaries

​

V1 support contract

​

Tools, media, and compaction

​

Troubleshooting

​

Related

• Agent harness plugins
• Agent runtimes
• Model providers
• OpenAI provider
• Status
• Plugin hooks
• Configuration reference
• Testing