OpenClaw

OpenClaw should use Codex Pooler through the narrow OpenAI-compatible /v1 surface. Keep openai/* model names when you want OpenClaw and its tools to treat the model as the canonical OpenAI provider path. The optional MCP block is only for operator metadata tools.

For a deployed instance, use these URLs:

OpenAI-compatible base URL:
https://codex-pooler.example.com/v1

Operator MCP URL:
https://codex-pooler.example.com/mcp

For local setup, replace the host with http://localhost:4000.

Provider shape

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-5.6-terra",
        list: [
          {
            id: "background",
            model: "openai/gpt-5.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: 300,
        models: [
          {
            id: "gpt-5.6-luna",
            name: "GPT-5.6 Luna via Codex Pooler",
            reasoning: true,
            input: ["text", "image"],
            contextWindow: 828400,
            contextTokens: 828400,
            maxTokens: 128000,
          },
          {
            id: "gpt-5.6-terra",
            name: "GPT-5.6 Terra via Codex Pooler",
            reasoning: true,
            input: ["text", "image"],
            contextWindow: 828400,
            contextTokens: 828400,
            maxTokens: 128000,
          },
          {
            id: "gpt-5.6-sol",
            name: "GPT-5.6 Sol via Codex Pooler",
            reasoning: true,
            input: ["text", "image"],
            contextWindow: 828400,
            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.

OpenClaw separates the configured contextWindow from the effective runtime contextTokens budget. The 828400 values above are long-profile examples for models whose selected Pool catalog source reports an 872000-token raw ceiling. Provider accounts can temporarily report different ceilings for the same model; a selected 272000-token profile exposes 258400 instead. Use each model’s /v1/models.context_length for both fields and do not configure the raw ceiling. For the long-profile example, the 128000-token compaction reserve keeps output accounting explicit and starts local compaction at 700400 tokens. Use gpt-5.6-luna for background routing, keep gpt-5.6-terra as the primary model, and switch a session to gpt-5.6-sol only for heavy reasoning.

Operator MCP server

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.

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-5.6-terra 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.

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.