bot/docs/providers/openai.md

summary, read_when, title

summary	read_when	title
Use OpenAI via API keys or Codex subscription in Hanzo Bot	You want to use OpenAI models in Hanzo Bot You want Codex subscription auth instead of API keys	OpenAI

OpenAI

OpenAI provides developer APIs for GPT models. Codex supports ChatGPT sign-in for subscription access or API key sign-in for usage-based access. Codex cloud requires ChatGPT sign-in. OpenAI explicitly supports subscription OAuth usage in external tools/workflows like Hanzo Bot.

Option A: OpenAI API key (OpenAI Platform)

Best for: direct API access and usage-based billing. Get your API key from the OpenAI dashboard.

CLI setup

openclaw onboard --auth-choice openai-api-key
# or non-interactive
openclaw onboard --openai-api-key "$OPENAI_API_KEY"

Config snippet

{
  env: { OPENAI_API_KEY: "sk-..." },
  agents: { defaults: { model: { primary: "openai/gpt-5.4" } } },
}

OpenAI's current API model docs list gpt-5.4 and gpt-5.4-pro for direct OpenAI API usage. Hanzo Bot forwards both through the openai/* Responses path. Hanzo Bot intentionally suppresses the stale openai/gpt-5.3-codex-spark row, because direct OpenAI API calls reject it in live traffic.

Hanzo Bot does not expose openai/gpt-5.3-codex-spark on the direct OpenAI API path. pi-ai still ships a built-in row for that model, but live OpenAI API requests currently reject it. Spark is treated as Codex-only in Hanzo Bot.

Option B: OpenAI Code (Codex) subscription

Best for: using ChatGPT/Codex subscription access instead of an API key. Codex cloud requires ChatGPT sign-in, while the Codex CLI supports ChatGPT or API key sign-in.

CLI setup (Codex OAuth)

# Run Codex OAuth in the wizard
openclaw onboard --auth-choice openai-codex

# Or run OAuth directly
openclaw models auth login --provider openai-codex

Config snippet (Codex subscription)

{
  agents: { defaults: { model: { primary: "openai-codex/gpt-5.4" } } },
}

OpenAI's current Codex docs list gpt-5.4 as the current Codex model. Hanzo Bot maps that to openai-codex/gpt-5.4 for ChatGPT/Codex OAuth usage.

If your Codex account is entitled to Codex Spark, Hanzo Bot also supports:

• openai-codex/gpt-5.3-codex-spark

Hanzo Bot treats Codex Spark as Codex-only. It does not expose a direct openai/gpt-5.3-codex-spark API-key path.

Hanzo Bot also preserves openai-codex/gpt-5.3-codex-spark when pi-ai discovers it. Treat it as entitlement-dependent and experimental: Codex Spark is separate from GPT-5.4 /fast, and availability depends on the signed-in Codex / ChatGPT account.

Transport default

Hanzo Bot uses pi-ai for model streaming. For both openai/* and openai-codex/*, default transport is "auto" (WebSocket-first, then SSE fallback).

You can set agents.defaults.models.<provider/model>.params.transport:

• "sse": force SSE
• "websocket": force WebSocket
• "auto": try WebSocket, then fall back to SSE

For openai/* (Responses API), Hanzo Bot also enables WebSocket warm-up by default (openaiWsWarmup: true) when WebSocket transport is used.

Related OpenAI docs:

• Realtime API with WebSocket
• Streaming API responses (SSE)

{
  agents: {
    defaults: {
      model: { primary: "openai-codex/gpt-5.4" },
      models: {
        "openai-codex/gpt-5.4": {
          params: {
            transport: "auto",
          },
        },
      },
    },
  },
}

OpenAI WebSocket warm-up

OpenAI docs describe warm-up as optional. Hanzo Bot enables it by default for openai/* to reduce first-turn latency when using WebSocket transport.

Disable warm-up

{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.4": {
          params: {
            openaiWsWarmup: false,
          },
        },
      },
    },
  },
}

Enable warm-up explicitly

{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.4": {
          params: {
            openaiWsWarmup: true,
          },
        },
      },
    },
  },
}

OpenAI priority processing

OpenAI's API exposes priority processing via service_tier=priority. In Hanzo Bot, set agents.defaults.models["openai/<model>"].params.serviceTier to pass that field through on direct openai/* Responses requests.

{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.4": {
          params: {
            serviceTier: "priority",
          },
        },
      },
    },
  },
}

Supported values are auto, default, flex, and priority.

OpenAI fast mode

Hanzo Bot exposes a shared fast-mode toggle for both openai/* and openai-codex/* sessions:

• Chat/UI: /fast status|on|off
• Config: agents.defaults.models["<provider>/<model>"].params.fastMode

When fast mode is enabled, Hanzo Bot applies a low-latency OpenAI profile:

• reasoning.effort = "low" when the payload does not already specify reasoning
• text.verbosity = "low" when the payload does not already specify verbosity
• service_tier = "priority" for direct openai/* Responses calls to api.openai.com

Example:

{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.4": {
          params: {
            fastMode: true,
          },
        },
        "openai-codex/gpt-5.4": {
          params: {
            fastMode: true,
          },
        },
      },
    },
  },
}

Session overrides win over config. Clearing the session override in the Sessions UI returns the session to the configured default.

OpenAI Responses server-side compaction

For direct OpenAI Responses models (openai/* using api: "openai-responses" with baseUrl on api.openai.com), Hanzo Bot now auto-enables OpenAI server-side compaction payload hints:

• Forces store: true (unless model compat sets supportsStore: false)
• Injects context_management: [{ type: "compaction", compact_threshold: ... }]

By default, compact_threshold is 70% of model contextWindow (or 80000 when unavailable).

Enable server-side compaction explicitly

Use this when you want to force context_management injection on compatible Responses models (for example Azure OpenAI Responses):

{
  agents: {
    defaults: {
      models: {
        "azure-openai-responses/gpt-5.4": {
          params: {
            responsesServerCompaction: true,
          },
        },
      },
    },
  },
}

Enable with a custom threshold

{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.4": {
          params: {
            responsesServerCompaction: true,
            responsesCompactThreshold: 120000,
          },
        },
      },
    },
  },
}

Disable server-side compaction

{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.4": {
          params: {
            responsesServerCompaction: false,
          },
        },
      },
    },
  },
}

responsesServerCompaction only controls context_management injection. Direct OpenAI Responses models still force store: true unless compat sets supportsStore: false.

Notes

• Model refs always use provider/model (see /concepts/models).
• Auth details + reuse rules are in /concepts/oauth.