OpenClaw Codex harness: sessions, credentials, and billing

The OpenClaw Codex harness is the official @openclaw/codex plugin: it hands an OpenClaw agent turn to OpenAI's Codex app-server so that Codex owns the model loop, thread resume, tool continuation and compaction. It is not a coding-delegation product, not a billing layer, and — the part that trips up most setups — not a way to run Codex against a third-party API endpoint. Which of those you actually need is the decision this page exists to make.

Dates first, so nothing here is undated. The npm package openclaw is at 2026.9.5 and requires Node >=24.16.0 <25 || >=26.1.0; @openclaw/codex is at 2026.9.5, published September 18, 2026. Both read from the registry on September 21, 2026. Three unrelated projects share these names and none of their numbers belong here: pjasicek/OpenClaw describes itself as a reimplementation of the 1997 platformer Captain Claw, the bare npm package codex is a "static site and code documentation generator" last published in 2012, and OpenAI's CLI is @openai/codex (0.155.1 on the same date).

Five OpenClaw surfaces share the name "Codex"

OpenClaw's agent-runtimes documentation calls these "intentionally independent". Picking the wrong one is the most common reason a configuration looks correct and does nothing.

A sixth name is not OpenClaw's at all. openclaw-code-agent is a third-party plugin that runs background coding sessions with plan approval and worktree isolation; its own README states it is separate from OpenClaw's bundled acpx runtime plugin and bundled core codex plugin. If you came here wanting delegation rather than a runtime swap, that is a different product with different config keys.

Turning the harness on, and proving it is on

The documented path is two commands — the plugin, then the sign-in.

openclaw plugins install @openclaw/codex
openclaw models auth login --provider openai

Then the minimum configuration. If you use a plugins.allow list, add "codex" to it as well.

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
      },
    },
  },
  agents: {
    defaults: {
      // The docs' own example ref. Legacy codex-cli/* refs are
      // repaired to the same openai/<model> route by doctor --fix.
      model: "openai/gpt-6-astra",
    },
  },
}

Two details the harness documentation is explicit about. Plugin config changes apply automatically in hybrid reload mode, but an existing chat needs /new or /reset first so the next turn resolves the harness from current config. And the effective tool profile must allow native shell and filesystem capabilities: coding and full do, while messaging and minimal disable the native surface. An ordinary OpenClaw sandbox or restricted tool policy is a narrower cut in the same documentation — it disables native code mode unless you opt into the experimental sandbox exec-server path — and when sandboxing does disable the native surface, allowed shell commands remain reachable through sandbox_exec.

Version requirements, checked September 21, 2026 against the app-server transport reference: the plugin manages stable Codex app-server 0.154.0, while explicit custom executables, remote app-servers and macOS desktop binaries must report a parseable semantic version of 0.149.0 or newer. npm's latest @openai/codex is 0.155.1 the same day, so the managed pin sits one patch behind — which is why any tutorial saying "Codex latest" without a date goes stale within days. Migrating an older setup matters too: the agent-runtimes page says OpenClaw's bundled Codex CLI backend was removed in v2026.5.14, and that legacy codex-cli/* refs repair to the same openai/<model> Codex app-server route under openclaw doctor --fix, which owns legacy Codex route repair generally.

To verify: a Codex-backed turn reports Runtime: OpenAI Codex under /status, and /codex status, /codex models and /codex binding inspect app-server state. A lint — openclaw doctor --lint --only codex/managed-app-server --json — checks the managed binary, but the docs describe it as read-only and put a selected Codex Desktop binary, an explicit custom command and a remote app-server outside that package check.

One tension worth knowing before you build on this. OpenAI's own app-server documentation states that "the app-server command and WebSocket transport are experimental and aren't supported for production workloads" — note that the warning names the command as well as the transport. OpenClaw builds a shipped feature on top of that command, and its transport field defaults to stdio, with websocket used only when you configure a url. Both statements are true at once; decide with both in view.

Delegation artifacts, permissions, cancel and resume

The harness documentation is honest about the limits of what a native subagent's status proves: execution, task result and result delivery are separate facts, an idle, interrupted or unloaded native thread does not prove the task succeeded, and when close confirmation is unavailable the task asks you to retry the close. Native Codex subagents are Codex's own mechanism — explicit OpenClaw or ACP delegation still goes through sessions_spawn.

Per the plugin's config-field table, execution permissions for the app-server OpenClaw spawns default to mode yolo, approval policy never and sandbox danger-full-access, unless local Codex requirements disallow that posture, in which case guardian defaults prefer on-request approvals and workspace-write, otherwise read-only; requestTimeoutMs, the timeout for app-server control-plane calls, defaults to 60000. These are OpenClaw's defaults for the process it launches, not Codex CLI's own, and on an unfamiliar repository that first default is the setting to review before the first run.

Control during a turn is native: /codex stop, /codex steer, /codex resume, /codex detach, /codex bind, /codex compact, /codex threads, /codex goal, /codex model, /codex fast and /codex permissions. A restricted turn is per-turn rather than a session mode, and it disables native Code Mode, environment selections, configured MCP servers and native hook relays for that turn only. OpenClaw's runtime v1 support contract also lists as unsupported: native tool-argument mutation (pre-tool hooks can block, but OpenClaw does not rewrite the arguments), an editable Codex-native transcript history, compaction intervention, and byte-for-byte model API request capture — so if your audit requirement is the exact outbound request, this runtime cannot supply it.

Authorization, plan entitlement and token spend are three different things

Read from OpenClaw's Codex app-server policy page on September 21, 2026. One naming trap sits on top of this: OpenAI's API pricing page says Priority processing was renamed Fast mode on July 30, 2026 and that you can send service_tier of either "priority" or "fast", while OpenClaw's appServer.serviceTier documents "priority" and "flex" and normalizes a legacy "fast" to "priority" — the opposite direction. "Turn on fast mode" means different things in the two systems.

Why a third-party endpoint leaves the harness

This is the single fact most third-party write-ups get backwards. OpenClaw's implicit agent runtime table, for a provider or model runtime that is unset or auto:

So pointing OpenClaw at any third-party base URL — Kunavo included — puts the turn on OpenClaw's built-in runtime, by design. The openai/* prefix alone never selects the harness, and forcing agentRuntime.id: "codex" does not rescue it. The runtimes page says that setting "requires a registered Codex harness; unsupported routes/auth fail closed, except that authored request overrides may use Codex's declared exact-request OpenClaw fallback before execution" — so the two outcomes are a failed turn or an OpenClaw turn, and neither is Codex on a custom endpoint. The plugin's documented config fields carry no model base-URL setting either; the one url field there is the app-server's own WebSocket or unix:// address. Whether appServer.args could smuggle a provider override into the managed app-server is undocumented and untested; this page does not present it as a workaround.

A built-in-runtime route also reshapes the request, and OpenClaw's custom-provider page is specific about the scope of each rule. For api: "openai-completions" on a non-native endpoint — which it defines as any non-empty baseUrl whose host is not api.openai.com — OpenClaw forces compat.supportsDeveloperRole to false, and overrides an explicit true. Separately, proxy-style OpenAI-compatible routes "skip native OpenAI-only request shaping": no service_tier, no Responses store, no Completions store, no prompt-cache hints, no OpenAI reasoning-compat payload shaping and no hidden attribution headers. With no service_tier on the wire, Fast mode and Flex are not selectable on such a route. What that same page offers instead is params.extra_body pass-through for OpenAI-compatible Completions proxies, per-provider headers, and models.providers.<id>.timeoutSeconds for slow or remote hosts.

Codex itself is the other half of the story, and it is more permissive: Codex's advanced-config page shows ~/.codex/config.toml supporting [model_providers.<id>] with base_url and env_key. But there is a hard gate — the config reference states that for model_providers.<id>.wire_api, "responses is the only supported value, and it is the default when omitted". An endpoint that serves only Chat Completions therefore cannot drive Codex. The same advanced-config page reserves the built-in ids openai, ollama and lmstudio, and lists model_provider and model_providers among the keys Codex ignores in a project-level .codex/config.toml, so provider keys belong in user-level config. Kunavo implements a native Responses surface at /v1/responses, which is what makes the Codex CLI setup possible — but that is standalone Codex CLI, not the OpenClaw harness, and Kunavo has not runtime-tested either client.

What the software costs, and what the tokens cost

OpenClaw itself is $0. Its documentation index describes the project as MIT-licensed, community-driven, developed by an independent 501(c)(3) foundation, with "No paid tier"; @openclaw/codex is published on the public npm registry at no charge. Every real cost is the machine you run the Gateway on plus model usage, and model usage arrives by one of three contracts.

From OpenAI's Codex pricing page, checked September 21, 2026. Three caveats belong with that table. The pricing card publishes only "From $100" for Pro; OpenAI's separate About ChatGPT Pro tiers article names a higher $200 tier whose new sign-ups and upgrades are paused as of September 10, 2026, so confirm at checkout rather than budgeting a number this page did not see on a pricing card. Included usage is published only as estimated ranges of local messages per five-hour period, not as a fixed message count. And credit rates after included limits are published in credits per million tokens, with no dollar value for a credit on that pricing page — so it supplies no dollar conversion for that row. Separately, GPT-5.5 retires from ChatGPT, ChatGPT Work and Codex on all plans on October 14, 2026, while the OpenAI API is not affected.

The third contract is a gateway on OpenClaw's built-in runtime. Assume one delegated turn that sends 180,000 uncached input tokens and receives 9,000 output tokens; rates are live Kunavo catalog prices per million tokens.

These are illustrative token arithmetic, not measured task costs and not a bill ceiling — the turn shape is an assumption, and a real agent turn re-sends context on every tool round trip. Kunavo's catalog amount is a billing floor rather than a cap: when the upstream reports its charge, the bill is the greater of catalog cost and upstream cost times the applicable markup. Cache charges and external tools sit outside the example. The minimum top-up is $10 in prepaid credit, which funds a balance rather than buying a plan — see billing details.

Kunavo serves no embedding model, no text-to-speech model and no speech-to-text model. Those steps are not served by Kunavo on any route, so take them to a provider that offers them.

That boundary matters here because the surfaces table above keeps a non-agent OpenAI Platform route separate from the harness, and a Gateway key covers only the chat models in the Kunavo catalog.

Which route wins when

If the answer is the gateway row, start at the Codex CLI integration for the Responses-API shape, compare options in the best API for OpenClaw and the best API for Codex, and create a Kunavo account when you are ready to fund a key. For the budget side of a self-hosted assistant, OpenClaw pricing separates software, hosting and model spend.

FAQ

The runtime table, auth order, app-server warning, wire_api gate, version pins and plan prices above were fetched on September 21, 2026 from OpenClaw's and OpenAI's own documentation, OpenAI's help centre, and the npm registry entries for openclaw, @openclaw/codex, @openai/codex, codex and openclaw-code-agent. Each claim is linked to the page it came from; where a document did not settle a question, the text says so rather than filling the gap. Kunavo has run no runtime test of OpenClaw or of the Codex harness, so every configuration here is checked against source documentation rather than demonstrated against Kunavo's endpoint. Kunavo token rates come from the live catalog, and each dollar figure is illustrative arithmetic.