# OpenClaw Integration

> **Zuletzt überprüft**: 2026-09-18 · 📄 Laut offizieller Dokumentation (OpenClaw v2026.9.4, veröffentlicht am 2026-09-11)

## Auf einen Blick

| Eintrag | Details |
|---|---|
| Verfügbare Modelle | Claude ✅ (Anthropic-Protokoll) · GPT ✅ · Chinesische Modelle ✅ · Gemini ⚠️ (der `google-generative-ai`-Adapter existiert upstream, wurde in diesem Durchgang nicht überprüft) |
| Protokoll & Base URL | Anthropic: `https://api.qcode.cc/api` · OpenAI: `https://api.qcode.cc/openai/v1` |
| Konfiguration | `~/.openclaw/openclaw.json` (JSON5, wird hot-reloaded) oder der `openclaw onboard`-Wizard |
| Offizielle Dokumentation | [Custom Providers](https://github.com/openclaw/openclaw/blob/main/docs/concepts/model-providers/custom-providers.md) · [docs.openclaw.ai](https://docs.openclaw.ai) |

OpenClaw ist ein **Open-Source-KI-Assistent, der auf Ihren eigenen Geräten läuft**: Ein selbst gehosteter Gateway-Prozess dockt an Discord, Telegram, Slack, iMessage und andere Chat-Kanäle an, mit nativen Apps für macOS / Windows / Linux. **Es ist kein Code-Editor** – es wird in diesem Abschnitt behandelt, weil es häufig als „persönlicher Assistent-Gateway über mehrere Modelle“ genutzt wird und weil es jeden OpenAI- / Anthropic-kompatiblen Endpunkt nativ unterstützt.

## Voraussetzungen

- OpenClaw installiert (offizielles Installationsprogramm `curl -fsSL https://openclaw.ai/install.sh | bash`; eine direkte npm-Installation benötigt Node 24.16+, offizielle Empfehlung ist 26+, siehe [README](https://github.com/openclaw/openclaw#readme)).
- Ein QCode.cc `cr_`-Schlüssel (erstellen Sie ihn im [Dashboard](https://qcode.cc/dashboard)). **Kein** Upstream-Anbieterkonto erforderlich.
- OpenClaw selbst benötigt kein eigenes Konto; jedes Modell stammt von den konfigurierten Anbietern.

## Einrichtung

### Route A: Konfigurationsdatei direkt bearbeiten (empfohlen)

Fügen Sie einen `models.providers`-Block in `~/.openclaw/openclaw.json` ein. Die Datei ist JSON5 (Kommentare und nachfolgende Kommas erlaubt), und der Gateway lädt sie hot-reload – kein Neustart erforderlich:

```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" },
        ],
      },
    },
  },
}
```

Drei Hinweise (alle aus der offiziellen [custom-providers doc](https://github.com/openclaw/openclaw/blob/main/docs/concepts/model-providers/custom-providers.md)):

- `apiKey` unterstützt `${ENV_VAR}`-Substitution; Upstream empfiehlt Geheimreferenzen / Umgebungsvariablen anstelle eines wörtlichen Schlüssels.
- `api` ist der Anfrageadapter: Die Anthropic-Seite ist `anthropic-messages`, die OpenAI-Seite ist `openai-completions`. Wird nur `baseUrl` ohne `api` gesetzt, greift die Voreinstellung `openai-completions`.
- Ein Modell erhält nur dann Bilder (Vision), wenn Sie ausdrücklich `input: ["text", "image"]` setzen; andernfalls werden Bilder als Textreferenzen übergeben.

### Route B: Der Custom-Provider-Eintrag im Onboard-Wizard

```bash
openclaw onboard --install-daemon
```

Wählen Sie **Custom Provider** in der Anbieterliste (unter **More…**, wenn er nicht direkt aufgeführt ist), und geben Sie dann die Base URL, den API-Key, die Kompatibilität und die Modell-ID ein. Der Wizard überprüft eine echte Antwort vor dem Speichern (offizielle Formulierung: *verifies a real reply before saving*), wodurch Tippfehler in der URL sofort erkannt werden.

Das nicht-interaktive Äquivalent für ein Claude-Modell:

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

🔴 Zwei Schreibweisen unterscheiden sich: Das Wizard-Flag `--custom-compatibility` erwartet `anthropic`, während das `api`-Feld in der Konfigurationsdatei `anthropic-messages` erwartet (siehe [Onboard-Dokumentation](https://github.com/openclaw/openclaw/blob/main/docs/cli/onboard.md)).

## Funktioniert es?

1. Falls Sie Route B verwendet haben, hat der Assistent bereits einen Live-Test für Sie durchgeführt (eine echte Anfrage vor dem Speichern).
2. Nach Route A fragen Sie den Agenten etwas Triviales wie `ping`. Falls es fehlschlägt, prüfen Sie zuerst die JSON5-Syntax von `~/.openclaw/openclaw.json` — Kommentare und überflüssige Kommas führen zu Fehlern.
3. Um nur zu prüfen, dass der Pfad existiert und der Key ankommt:

```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. Jede Anfrage (auch die von OpenClaw) wird auf [probe.qcode.cc](https://probe.qcode.cc) protokolliert — geben Sie Ihren Key ein, um das Modell und den Status tatsächlicher Anfragen zu sehen. Immer noch Fehler? Folgen Sie der Checkliste unter [Fehlerbehebung](/docs/reference/troubleshooting).

## Bekannte Einschränkungen

- **Vorbehalt zur Base-URL-Form**: Beide offiziellen `anthropic-messages`-Beispiele (Synthetic, MiniMax) verwenden eine `baseUrl` **ohne `/v1`** (z. B. `https://api.minimax.io/anthropic`), daher verwendet diese Seite `https://api.qcode.cc/api`. Der genaue Pfad, den OpenClaw anhängt, ist nicht wortgetreu dokumentiert und wurde hier nicht live getestet. Falls Anfragen 404 zurückgeben, ändern Sie `baseUrl` auf den vollständigen Pfad `https://api.qcode.cc/api/v1/messages`.
- Der `openai-responses`-Adapter ist für Backends dokumentiert, die nur `/v1/responses` unterstützen. Auf QCode bedient der Responses-Zweig GPT-Modelle; leiten Sie chinesische Modelle über `openai-completions` (Protokollmatrix: [Endpunkte und API-Pfade](/docs/getting-started/endpoints-and-api-paths)).
- Bei Nicht-Direkt-`anthropic-messages`-Endpunkten unterdrückt OpenClaw Anthropic-Beta-Header stromaufwärts (dokumentiertes Verhalten) — hilfreich für Drittanbieter-Gateways. Falls ein anderes Tool `anthropic-beta`-400-Fehler erzeugt, ist das kein OpenClaw-Problem.
- Der Gemini-Zweig (`google-generative-ai`) existiert im offiziellen Enum, aber die QCode-`/gemini`-Base-URL-Form wurde in diesem Durchgang nicht verifiziert, daher ist noch kein Beispiel verfügbar.
- Die offiziellen Dokumente befinden sich auf dem GitHub-`main`-Branch; docs.openclaw.ai kann leicht dahinter zurückliegen.

## Verwandte Dokumente

- [Endpunkte und API-Pfade](/docs/getting-started/endpoints-and-api-paths) — die vier Protokollzweige und wie man Base URLs einträgt
- [Tool-Kompatibilitätsübersicht](/docs/ide/tool-compatibility) — Protokollunterstützung über alle Tools hinweg
- [CC Switch Setup](/docs/ide/cc-switch) — GUI-Anbieterwechsel für Claude Code / Codex
- [Chinesische Modelle](/docs/usage/cn-models) — aktuell verfügbare GLM- / Kimi- / DeepSeek- / Qwen-IDs
- [Fehlerbehebung](/docs/reference/troubleshooting)