Use Plan2API as a custom provider in OpenClaw

OpenClaw settings for Plan2API

OpenClaw talks to Plan2API as a custom provider that uses the OpenAI-compatible Chat Completions format, set up in its config file. The table below lists the values to put in your config.

When Plan2API helps in OpenClaw

OpenClaw already signs in to ChatGPT and Codex with OAuth, reuses a local Claude CLI login (and setup-token auth still works), and takes Anthropic, Google AI Studio, Vertex AI and Kimi API keys. However, it doesn't create Gemini CLI or Antigravity OAuth profiles.

• Use Gemini models from a Google AI Pro or Ultra plan through Antigravity.
• Keep one p2a_ key and one models.providers entry across your Claude, Codex, Gemini and Kimi plans.
• Run the gateway on a remote server where there's no local CLI login by connecting a Claude Pro or Max subscription as an API.
• Connect several accounts of the same provider, so a request that hits a usage limit moves to the next account before any output is sent.

Add Plan2API to openclaw.json

1. Sign up with a Google account, connect your Claude, ChatGPT, Google AI or Kimi subscription, and copy your p2a_ key.
2. Put PLAN2API_KEY in ~/.openclaw/.env or in the gateway's environment, since the config's apiKey field reads ${PLAN2API_KEY} and only matches uppercase names.
3. Add the provider block to ~/.openclaw/openclaw.json (or the file in OPENCLAW_CONFIG_PATH), listing each model you want to use with at least its id.
4. Save the file so the config hot-reloads; OpenClaw validates keys strictly, and an unknown key stops the gateway from starting until you run openclaw doctor --fix.

This example adds the provider block and sets the primary model at the same time.

{
  "agents": {
    "defaults": {
      "model": { "primary": "plan2api/claude/claude-sonnet-5" }
    }
  },
  "models": {
    "providers": {
      "plan2api": {
        "baseUrl": "https://api.plan2api.com/v1",
        "apiKey": "${PLAN2API_KEY}",
        "api": "openai-completions",
        "timeoutSeconds": 300,
        "models": [
          {
            "id": "claude/claude-sonnet-5",
            "name": "Claude Sonnet 5 (Plan2API)",
            "reasoning": true,
            "input": ["text", "image"],
            "contextWindow": 1000000
          },
          {
            "id": "openai/gpt-6.1-sol",
            "name": "GPT-6.1 Sol (Plan2API)",
            "reasoning": true
          },
          {
            "id": "gemini/gemini-3.8-flash-high",
            "name": "Gemini 3.8 Flash (Plan2API)",
            "reasoning": true,
            "input": ["text", "image"],
            "contextWindow": 1048576
          },
          {
            "id": "kimi/k3",
            "name": "Kimi K3 (Plan2API)",
            "reasoning": true,
            "input": ["text", "image"],
            "contextWindow": 1048576
          }
        ]
      }
    }
  }
}

Pick the default model

OpenClaw model refs follow a provider/model format and split at the first slash. That means plan2api/claude/claude-sonnet-5 tells OpenClaw to use the plan2api provider and send the model id claude/claude-sonnet-5 to the API.

You can set the default in agents.defaults.model.primary, run openclaw models set plan2api/claude/claude-sonnet-5 in your terminal, or pick it in the Control UI (http://127.0.0.1:18789, under Settings, then Models). Run openclaw models list any time to see the available refs. The table below lists the common model refs along with the contextWindow value to set for each one (without contextWindow and with no discovered window, OpenClaw falls back to a 200,000-token budget).

Thinking, images and timeouts

• Setting reasoning: true on a model makes OpenClaw send reasoning_effort when thinking is turned on (while /think off omits it), which works across all four providers, though xhigh and max require compat.supportedReasoningEfforts on the model entry.
• Setting input to ["text", "image"] lets WebChat and node attachments reach Claude, Gemini and Kimi models as images instead of text-only media references.
• Leaving maxTokens unset tells OpenClaw to send neither max_tokens nor max_completion_tokens, and Claude models then allow up to 128K output (or 64K on claude/claude-haiku-4-5).
• Setting timeoutSeconds under models.providers.plan2api extends OpenClaw's default 120-second wait for the first response from a cloud endpoint, which helps on long reasoning turns.

Plan2API plans for OpenClaw agents

An OpenClaw agent sends one chat request per model call, so a single task with tool calls and follow-up turns can go through several requests. The Free plan ($0, no card needed) includes 1 connected subscription, 50 chat requests a day resetting at 00:00 UTC, 1 request per second with bursts up to 20, and 4 requests at once, which is plenty for testing your config.

For daily agent runs, Pro is $12 a month or $99 a year with no daily request cap, 10 requests per second with bursts up to 600, 16 requests at once and 3 connected subscriptions, while Scale is $29 a month or $249 a year with 25 subscriptions and 32 requests at once. Plan2API never bills per token and adds no token quota of its own, so Claude's own usage limits and your other providers' limits still apply alongside the Plan2API plan limits and pricing.

Troubleshooting OpenClaw with Plan2API

• Gateway won't start after editing ~/.openclaw/openclaw.json: OpenClaw stops on unknown or misspelled keys, so run openclaw doctor --fix to repair the config.
• 401 invalid_api_key: PLAN2API_KEY isn't set in the gateway's process environment or ~/.openclaw/.env, so ${PLAN2API_KEY} stays unresolved and OpenClaw emits a warning; a revoked or mistyped key gives the same 401.
• 403 no_credentials: your vault has no connected subscription for the provider prefix on that model id.
• 400 model_not_found: the models[].id entry in your config needs to be the exact model id from GET /v1/models, such as claude/claude-sonnet-5 without the plan2api/ prefix.
• 400 unsupported_parameter: the request sent a json_object or json_schema response_format to a Claude model, which only accepts text responses.
• 429 subscription_quota_exhausted with a Retry-After header: every connected account for that provider has hit its usage limit until the reset time in Retry-After (or on the Free plan, 429 daily_requests when you pass 50 chat requests before 00:00 UTC).

See the API documentation and error reference for the full list of error codes and streaming error events.