OpenClaw on Codex Pooler

OpenClaw is an open-source AI assistant that runs on your own devices and connects to the chat channels you use. It can carry out tasks with tools while keeping conversations available through its gateway. Connect it to Codex Pooler to use your Pool’s models for the main assistant and background tasks.

Codex Pooler OpenClaw integration

Before you start

Install OpenClaw using the official instructions for your operating system.
Have a Codex Pooler URL reachable from the client.
Create a Pool API key and choose a model available to that Pool.

Configure the connection

Use the commands for the terminal that starts the client. Environment-variable assignments below apply to that terminal; desktop apps and services need the variables in their own launch environment.

Config file paths

OS	Default config file
macOS	`~/.openclaw/openclaw.json`
Linux	`~/.openclaw/openclaw.json`
Windows	`%USERPROFILE%\.openclaw\openclaw.json`

If you set OPENCLAW_CONFIG_PATH, edit that file instead of the default shown below.

These are the default locations. On Windows, paste the %USERPROFILE%, %APPDATA% or %LOCALAPPDATA% path into File Explorer’s address bar. For a client installed inside WSL, use the Linux paths and commands inside WSL. Keep any custom configuration folder or profile you already use.

Merge the following settings into openclaw.json at the path for your system, or the file selected by OPENCLAW_CONFIG_PATH. Make CODEX_POOLER_API_KEY available to the running OpenClaw process:

macOS / Linux / WSL

export CODEX_POOLER_API_KEY="<pool-api-key>"

Windows PowerShell

$env:CODEX_POOLER_API_KEY = "<pool-api-key>"

OpenClaw’s OpenAI provider should point baseUrl at Codex Pooler’s /v1 surface, use a Pool API key for model requests, and pin the agent runtime to openclaw. The older pi runtime id is a deprecated alias and should not be used in new Codex Pooler examples.

{
  agents: {
    defaults: {
      model: {
        primary: "openai/gpt-6-sol",
        list: [
          {
            id: "background",
            model: "openai/gpt-6-luna",
          },
        ],
      },
      compaction: { reserveTokens: 128000 },
    },
  },
  models: {
    mode: "merge",
    providers: {
      openai: {
        baseUrl: "https://codex-pooler.example.com/v1",
        apiKey: "${CODEX_POOLER_API_KEY}",
        api: "openai-responses",
        agentRuntime: { id: "openclaw" },
        timeoutSeconds: 120,
        models: [
          {
            id: "gpt-6-luna",
            name: "GPT-6 Luna via Codex Pooler",
            reasoning: true,
            input: ["text", "image"],
            contextWindow: 872000,
            contextTokens: 828400,
            maxTokens: 128000,
          },
          {
            id: "gpt-6-sol",
            name: "GPT-6 Sol via Codex Pooler",
            reasoning: true,
            input: ["text", "image"],
            contextWindow: 872000,
            contextTokens: 828400,
            maxTokens: 128000,
          },
          {
            id: "gpt-6-astra",
            name: "GPT-6 Astra via Codex Pooler",
            reasoning: true,
            input: ["text", "image"],
            contextWindow: 872000,
            contextTokens: 828400,
            maxTokens: 128000,
          },
        ],
      },
    },
  },
}

Define only model ids your assigned Pool can serve. If you run Codex Pooler locally, set baseUrl to http://localhost:4000/v1.

Choose a model

OpenClaw separates the configured contextWindow from the effective runtime contextTokens budget. The 872000 raw-context / 828400 effective-budget values above are long-profile examples. Provider accounts can temporarily report different ceilings for the same model; a selected 272000-token profile exposes 258400 effective tokens. Use each model’s /v1/models.context_length for contextWindow; set contextTokens to floor(0.95 * context_length) and do not configure the raw ceiling as the effective budget. For the long-profile example, the 128000-token compaction reserve keeps output accounting explicit and starts local compaction at 700400 tokens. Use gpt-6-luna for background routing, keep gpt-6-sol as the primary model, and select gpt-6-astra only when its Pool assignment permits it.

Verify the connection

Start a new OpenClaw conversation with the configured primary model and send a short request. In Codex Pooler’s request logs, match the request time, API key, model, and final status to your test. A reply alone does not confirm that the client used your Pooler instance.

If you configured a background model, check a background request as well: it must use a model available to the same Pool.

Advanced configuration

Custom provider option

If you want to keep Codex Pooler separate from OpenClaw’s built-in OpenAI provider behavior, you can use a custom provider id such as codex-pooler/gpt-6-sol instead.

That follows OpenClaw’s generic custom-provider shape, but tools that look specifically for openai/gpt-* model refs won’t see it as canonical OpenAI. Prefer the openai provider shape above unless you need that separation.

Operator MCP (optional)

Add Codex Pooler as a remote Streamable HTTP MCP server only when OpenClaw should inspect metadata that the operator can already see in the admin UI. Omit this block for normal model/runtime use.

{
  mcp: {
    servers: {
      codex_pooler: {
        url: "https://codex-pooler.example.com/mcp",
        transport: "streamable-http",
        headers: {
          Authorization: "Bearer <operator-mcp-token>",
        },
      },
    },
  },
}

Use http://localhost:4000/mcp only for local setup.

MCP uses an operator-owned MCP token, not a Pool API key. Don’t reuse the Pool API key from the model provider block for /mcp.

Compatibility notes

OpenClaw model requests use Codex Pooler’s narrow OpenAI-compatible /v1 support for selected SDK routes. Codex Pooler doesn’t provide full OpenAI API parity.

GET /v1/responses is narrow Responses websocket compatibility, not /v1/realtime support. /v1/realtime and OpenAI Realtime SDK websocket or session routes are unsupported.

The operator MCP endpoint is rooted at /mcp. It uses an operator-owned MCP token, not a Pool API key.