# Droid (Factory) Einrichtung

> **Zuletzt überprüft**: 2026-09-18 · 📄 Gemäß offizieller Dokumentation (Droid CLI v0.222.0 veröffentlicht am 2026-09-18; häufige Releases — verlassen Sie sich auf `droid --version`)

## Auf einen Blick

| Eintrag | Details |
|---|---|
| Verfügbare Modelle | Claude ✅ (`provider: "anthropic"`) · GPT ✅ · Chinesische Modelle ✅ (`provider: "generic-chat-completion-api"`) · Gemini ❌ (kein solcher Anbieter upstream) |
| Protokoll & Base URL | Anthropic: `https://api.qcode.cc/api` · OpenAI Chat: `https://api.qcode.cc/openai/v1` |
| Konfigurationsort | `~/.factory/settings.json` (wird bei der ersten `droid`-Ausführung automatisch erstellt) |
| Offizielle Dokumentation | [BYOK](https://docs.factory.ai/model-independence/byok) · [Settings](https://docs.factory.ai/droid-cli/settings)
[Droid](https://docs.factory.ai/droid-cli/overview) ist der Terminal-Coding-Agent von Factory. Er unterstützt **BYOK-Modelle**, sodass QCode.cc als Upstream-Anbieter dienen kann.

## Welches Protokoll

Droid wählt das Protokoll über das Feld `provider`. **Für Claude verwenden Sie `anthropic`** — der OpenAI-Endpunkt von QCode akzeptiert keine Claude-Modelle (siehe [Endpunkte & API-Pfade](/docs/getting-started/endpoints-and-api-paths)).

| Gewünschtes Modell | `provider` | `baseUrl` |
|---|---|---|
| Claude | `anthropic` | `https://api.qcode.cc/api` |
| GPT / die vier chinesischen Familien | `generic-chat-completion-api` (Chat-Completions-kompatibel) | `https://api.qcode.cc/openai/v1` |

> 🔴 Schreiben Sie **nicht** `"provider": "openai"` — upstream reserviert es für die **OpenAI Responses API** (“Use provider: `"generic-chat-completion-api"` unless you are calling OpenAI's or Anthropic's official API”, [BYOK-Dokumentation](https://docs.factory.ai/model-independence/byok)). GPT / chinesische Modelle auf QCode sprechen Chat Completions, verwenden Sie daher `generic-chat-completion-api`.

## Installation

```bash
curl -fsSL https://app.factory.ai/cli | sh
```

Installiert wird nach `~/.local/bin/droid`. Falls der Installer meldet, dass PATH nicht konfiguriert ist, fügen Sie die angezeigte Zeile zu `~/.zshrc` / `~/.bashrc` hinzu.

Überprüfen Sie (**verlassen Sie sich auf die tatsächliche Ausgabe**):

```bash
droid --version
```

## Konfiguration

Bearbeiten Sie `~/.factory/settings.json` (**sie wird bei der ersten `droid`-Ausführung automatisch erstellt**; eine projektweite `.factory/settings.local.json` funktioniert ebenfalls — sie wird darüber zusammengeführt, vergessen Sie nicht, sie in die gitignore aufzunehmen):

```json
{
  "customModels": [
    {
      "model": "claude-sonnet-5",
      "displayName": "QCode Sonnet 5",
      "baseUrl": "https://api.qcode.cc/api",
      "apiKey": "${QCODE_KEY}",
      "provider": "anthropic",
      "maxOutputTokens": 8192
    },
    {
      "model": "claude-haiku-4-5",
      "displayName": "QCode Haiku 4.5",
      "baseUrl": "https://api.qcode.cc/api",
      "apiKey": "${QCODE_KEY}",
      "provider": "anthropic",
      "maxOutputTokens": 4096
    }
  ]
}
```

Injizieren Sie den API-Key über die Umgebung:

```bash
export QCODE_KEY="cr_your_qcode_key"
```

| Feld | Bedeutung |
|-------|---------|
| `model` | Die Modell-ID, die an die API gesendet wird; muss exakt mit [qcode.cc/models](https://qcode.cc/models) übereinstimmen |
| `displayName` | Beschriftung in der Modellauswahl; frei wählbar |
| `baseUrl` | Endet auf `/api`; Droid hängt `/v1/messages` selbst an |
| `apiKey` | Unterstützt `${VAR}`-Umgebungsreferenzen |
| `provider` | `anthropic` für Claude |
| `maxOutputTokens` | Ausgabe-Limit pro Antwort |

> Laut Factory-Dokumentation **bleiben API-Keys lokal und werden nicht auf Factory-Server hochgeladen**.
> Von Festland-China aus ersetzen Sie den Host durch `https://asia.qcode.cc/api` (Asien-Knoten, nächstgelegener von Korea / Taiwan / Hongkong).

## Überprüfung

```bash
droid exec --model "claude-sonnet-5" "reply with exactly: OK"
```

`OK` bedeutet, dass die Verbindung hergestellt ist.

**Negativkontrolle** (zum Nachweis, dass die Konfiguration tatsächlich greift): Ändern Sie `baseUrl` vorübergehend auf einen nicht existierenden Pfad und führen Sie den Befehl erneut aus — er sollte fehlschlagen. Ein Erfolg allein beweist nicht, dass Ihre Leitung verwendet wurde.

## Tägliche Verwendung

```bash
# interactive
droid

# non-interactive
droid exec "run the tests and fix the failures"

# specific working directory
droid --cwd /path/to/project

# run inside a git worktree (isolated changes)
droid -w feature-x

# autonomy level
droid --auto medium
```

## Fehlerbehebung

### `model_not_available_on_endpoint`

Der `provider` ist ein OpenAI-kompatibler Wert, während das Modell ein Claude-Modell ist. Setzen Sie `"provider": "anthropic"` mit `baseUrl` = `https://api.qcode.cc/api`.

### 401 / Authentifizierungsfehler

`${QCODE_KEY}` wurde nicht expandiert (die Variable ist nicht exportiert), oder der API-Key enthält Leerzeichen. Prüfen Sie, dass `echo $QCODE_KEY` mit `cr_` beginnt.
Eine weitere Falle: die Konfiguration in die **Legacy-Datei** `~/.factory/config.json` (snake_case-Felder) geschrieben — laut Dokumentation expandiert die Legacy-Datei **keine** `apiKey`-Umgebungsreferenzen, sodass `${QCODE_KEY}` unverändert als Key gesendet würde. Verwenden Sie `settings.json`.

### Das Modell fehlt in der Auswahl

Es erscheinen nur Modelle, die in `customModels[]` aufgeführt sind. Fügen Sie einen Eintrag hinzu und starten Sie neu.

## Weiterführendes

- [Endpunkte & API-Pfade](/docs/getting-started/endpoints-and-api-paths) — Tabelle Protokoll × Modellfamilie
- [Crush Einrichtung](/docs/ide/crush) — ein anderer Coding-Agent im Terminal
- [Chinesische Modelle](/docs/usage/cn-models) — GLM / Kimi / DeepSeek / Qwen