OpenClaw Integration

Configure QCode.cc as model providers for OpenClaw: the models.providers block in openclaw.json, the Custom Provider onboarding wizard, and how to verify the connection

Last verified: 2026-09-18 · 📄 Per official docs (OpenClaw v2026.9.4, released 2026-09-11)

At a glance¶

OpenClaw is an open-source AI assistant that runs on your own devices: a self-hosted Gateway process plugs into Discord, Telegram, Slack, iMessage and other chat channels, with native apps for macOS / Windows / Linux. It is not a code editor — it lives in this section because it is frequently used as a "personal assistant gateway over multiple models", and because it natively supports any OpenAI / Anthropic compatible endpoint.

Prerequisites¶

• OpenClaw installed (official installer curl -fsSL https://openclaw.ai/install.sh | bash; a direct npm install needs Node 24.16+, official recommendation is 26+, see the README).
• A QCode.cc cr_ key (create one in the dashboard). No upstream vendor account is needed.
• OpenClaw itself requires no account of its own; every model comes from the providers you configure.

Setup¶

Route A: edit the config file directly (recommended)¶

Add a models.providers block to ~/.openclaw/openclaw.json. The file is JSON5 (comments and trailing commas allowed) and the Gateway hot-reloads it — no restart needed:

{
  models: {
    mode: "merge", // keep built-in providers, append QCode
    providers: {
      qcode: {
        baseUrl: "https://api.qcode.cc/api",
        apiKey: "${QCODE_API_KEY}",
        api: "anthropic-messages",
        models: [
          { id: "claude-sonnet-5", name: "Claude Sonnet 5", input: ["text", "image"] },
        ],
      },
      qcode_openai: {
        baseUrl: "https://api.qcode.cc/openai/v1",
        apiKey: "${QCODE_API_KEY}",
        api: "openai-completions",
        models: [
          { id: "gpt-5.6", name: "GPT-5.6" },
          { id: "glm-5.3", name: "GLM-5.3" },
        ],
      },
    },
  },
}

Three notes (all from the official custom-providers doc):

• apiKey supports ${ENV_VAR} substitution; upstream recommends secret references / env vars over a literal key.
• api is the request adapter: the Anthropic leg is anthropic-messages, the OpenAI leg is openai-completions. Setting only baseUrl without api defaults to openai-completions.
• A model only receives images (vision) if you explicitly set input: ["text", "image"]; otherwise images are passed as text references.

Route B: the Custom Provider entry in the onboard wizard¶

openclaw onboard --install-daemon

Pick Custom Provider in the provider list (under More… when it is not listed directly), then enter the base URL, API key, compatibility and model ID. The wizard verifies a real completion before saving (official wording: verifies a real reply before saving), which catches typos in the URL immediately.

The non-interactive equivalent, for a Claude model:

openclaw onboard --non-interactive --accept-risk \
  --auth-choice custom-api-key \
  --custom-base-url "https://api.qcode.cc/api" \
  --custom-model-id "claude-sonnet-5" \
  --custom-api-key "$QCODE_API_KEY" \
  --custom-compatibility anthropic

🔴 Two spellings differ: the wizard flag --custom-compatibility takes anthropic, while the config file's api takes anthropic-messages (see onboard docs).

Verify it works¶

1. If you used Route B, the wizard already ran a live check for you (one real request before saving).
2. After Route A, ask the agent something trivial like ping. If it fails, first check the JSON5 syntax of ~/.openclaw/openclaw.json — comments and stray commas break it.
3. To check only that the path exists and the key arrives:

curl -s -o /dev/null -w '%{http_code}\n' -X POST https://api.qcode.cc/api/v1/messages \
  -H "x-api-key: $QCODE_API_KEY"
# → 401 = key invalid; any code other than a JSON error = path reachable

1. Every request (including OpenClaw's) is logged at probe.qcode.cc — enter your key to see the model and status of actual requests. Still failing? Follow the checklist in Troubleshooting.

Known limitations¶

• Base URL form caveat: both official anthropic-messages examples (Synthetic, MiniMax) use a baseUrl without /v1 (e.g. https://api.minimax.io/anthropic), so this page uses https://api.qcode.cc/api. The exact path OpenClaw appends is not documented verbatim and was not live-tested here. If requests return 404, switch baseUrl to the full path https://api.qcode.cc/api/v1/messages.
• The openai-responses adapter is documented for backends that support /v1/responses only. On QCode the Responses leg serves GPT models; route Chinese models through openai-completions (protocol matrix: Endpoints and API paths).
• On non-direct anthropic-messages endpoints OpenClaw suppresses Anthropic beta headers upstream (documented behavior) — helpful for third-party gateways. If another tool hits anthropic-beta 400s, that is not an OpenClaw problem.
• The Gemini leg (google-generative-ai) exists in the official enum, but the QCode /gemini base URL form has not been verified in this pass, so no example is provided yet.
• Official docs live on the GitHub main branch; docs.openclaw.ai may lag slightly behind.

Related docs¶

• Endpoints and API paths — the four protocol legs and how to fill Base URLs
• Tool Compatibility Overview — protocol support across all tools
• CC Switch Setup — GUI provider switching for Claude Code / Codex
• Chinese Models — current GLM / Kimi / DeepSeek / Qwen ids on sale
• Troubleshooting