# OpenClaw Integration

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

## At a glance

| Item | Details |
|---|---|
| Models you can use | Claude ✅ (Anthropic protocol) · GPT ✅ · Chinese models ✅ · Gemini ⚠️ (the `google-generative-ai` adapter exists upstream, not verified in this pass) |
| Protocol & Base URL | Anthropic: `https://api.qcode.cc/api` · OpenAI: `https://api.qcode.cc/openai/v1` |
| Where to configure | `~/.openclaw/openclaw.json` (JSON5, hot-reloaded) or the `openclaw onboard` wizard |
| Official docs | [Custom Providers](https://github.com/openclaw/openclaw/blob/main/docs/concepts/model-providers/custom-providers.md) · [docs.openclaw.ai](https://docs.openclaw.ai) |

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](https://github.com/openclaw/openclaw#readme)).
- A QCode.cc `cr_` key (create one in the [dashboard](https://qcode.cc/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:

```json5
{
  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](https://github.com/openclaw/openclaw/blob/main/docs/concepts/model-providers/custom-providers.md)):

- `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

```bash
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:

```bash
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](https://github.com/openclaw/openclaw/blob/main/docs/cli/onboard.md)).

## 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:

```bash
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
```

4. Every request (including OpenClaw's) is logged at [probe.qcode.cc](https://probe.qcode.cc) — enter your key to see the model and status of actual requests. Still failing? Follow the checklist in [Troubleshooting](/docs/reference/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](/docs/getting-started/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](/docs/getting-started/endpoints-and-api-paths) — the four protocol legs and how to fill Base URLs
- [Tool Compatibility Overview](/docs/ide/tool-compatibility) — protocol support across all tools
- [CC Switch Setup](/docs/ide/cc-switch) — GUI provider switching for Claude Code / Codex
- [Chinese Models](/docs/usage/cn-models) — current GLM / Kimi / DeepSeek / Qwen ids on sale
- [Troubleshooting](/docs/reference/troubleshooting)