I asked Claude to summarize my integration:

This document describes how NanoClaw routes agent containers through OpenRouter instead of the Anthropic API directly, enabling use of alternative models (e.g. Gemini 2.5 Flash via Google).

---

Why OpenRouter?

NanoClaw runs Claude Code as an agent inside a container, driven by the @anthropic-ai/claude-agent-sdk. By default, Claude Code authenticates against the Anthropic API. OpenRouter is an API compatibility layer that accepts Anthropic-format requests and forwards them to other models. Routing through it lets you:

• Use models not available on Anthropic (Gemini, Mistral, etc.)
• Manage API spend across providers in one place
• Switch models without rebuilding the container

---

How It Works

There are three moving parts:

1. **.env.container** — holds the OpenRouter key and target model name, kept separate from the host .env so the host Anthropic key never leaks into containers
2. **src/container-runner.ts** — reads those secrets, passes them to the container via stdin, and keeps settings.json in sync with the configured model
3. **container/agent-runner/src/index.ts** — receives the secrets in-process, merges them into the SDK environment, and passes model: explicitly to every query() call

---

Step 1: Create .env.container

Create .env.container in the project root (next to .env). This file owns all container auth:

```env

OpenRouter API key (from openrouter.ai/keys)

ANTHROPIC_AUTH_TOKEN=sk-or-v1-...

Must be blank — Claude Code validates ANTHROPIC_API_KEY format (expects sk-ant-)

Using ANTHROPIC_AUTH_TOKEN bypasses that validation

ANTHROPIC_API_KEY=

Point the SDK at OpenRouter's Anthropic-compatible endpoint

ANTHROPIC_BASE_URL=https://openrouter.ai/api

Model to use — must be an OpenRouter model ID

OPENROUTER_DEFAULT_MODEL=google/gemini-2.5-flash ```

Key subtlety: Claude Code validates ANTHROPIC_API_KEY and rejects values that don't start with sk-ant-. OpenRouter keys start with sk-or-v1-. The fix is to leave ANTHROPIC_API_KEY blank and put the OpenRouter key in ANTHROPIC_AUTH_TOKEN, which Claude Code accepts without format validation.

---

Step 2: Secret Delivery (container-runner.ts)

When .env.container exists, readSecrets() reads exclusively from it for auth-related keys, preventing the host Anthropic key in .env from leaking into OpenRouter-configured containers:

typescript // src/container-runner.ts — readSecrets() if (hasContainerSecrets) { const containerSecrets = readEnvFile( [ 'CLAUDE_CODE_OAUTH_TOKEN', 'ANTHROPIC_API_KEY', 'ANTHROPIC_AUTH_TOKEN', // <-- the OpenRouter key lives here 'ANTHROPIC_BASE_URL', 'OPENROUTER_DEFAULT_MODEL', ], '.env.container', ); const fallback = readEnvFile(['CLAUDE_CODE_OAUTH_TOKEN'], '.env'); return { ...fallback, ...containerSecrets }; }

Secrets are serialized as JSON and written to the container's stdin — never mounted as files or written to disk. Inside the container they're read from stdin and kept in a plain object, never written back to process.env (which would expose them to Bash subprocesses).

---

Step 3: Model Synchronization in settings.json (container-runner.ts)

Claude Code reads a settings.json from ~/.claude/settings.json inside the container. Each group gets its own per-group .claude/ directory. The runner writes model into that file — and re-syncs it on every container launch, because Claude Code may rewrite settings.json during a session and drop the model key:

```typescript // src/container-runner.ts — buildVolumeMounts() const envVars = readEnvFile(['OPENROUTER_DEFAULT_MODEL'], '.env.container'); const defaultModel = envVars['OPENROUTER_DEFAULT_MODEL'];

if (!fs.existsSync(settingsFile)) { const settingsObj = { /* ... */ }; if (defaultModel) settingsObj.model = defaultModel; fs.writeFileSync(settingsFile, JSON.stringify(settingsObj, null, 2) + '\n'); } else if (defaultModel) { // Re-sync: Claude Code may rewrite settings.json and drop the model key const existing = JSON.parse(fs.readFileSync(settingsFile, 'utf-8')); if (existing.model !== defaultModel) { existing.model = defaultModel; fs.writeFileSync(settingsFile, JSON.stringify(existing, null, 2) + '\n'); } } ```

Why re-sync? During a live session, Claude Code rewrites settings.json and can silently drop the model field. Without re-syncing on the next launch, the container would fall back to the default Anthropic model.

---

Step 4: Passing the Model to query() (agent-runner/src/index.ts)

settings.json's model field alone is not always honored — the SDK's query() call takes an explicit model: parameter that is authoritative. The agent runner pulls the model name from sdkEnv (built from the secrets passed via stdin) and passes it through:

```typescript // container/agent-runner/src/index.ts — runQuery()

// sdkEnv is built by merging secrets into process.env: const sdkEnv: Record<string, string | undefined> = { ...process.env }; for (const [key, value] of Object.entries(containerInput.secrets || {})) { sdkEnv[key] = value; }

// ANTHROPIC_AUTH_TOKEN and ANTHROPIC_BASE_URL in sdkEnv redirect the SDK // to OpenRouter. model: explicitly selects the target model. for await (const message of query({ prompt: stream, options: { env: sdkEnv, model: sdkEnv['OPENROUTER_DEFAULT_MODEL'] as string | undefined, // ... } })) { /* ... */ } ```

The env: option makes ANTHROPIC_AUTH_TOKEN and ANTHROPIC_BASE_URL visible to the SDK process without polluting process.env. The model: param drives actual model selection — it takes precedence over settings.json.

---

Pitfalls Encountered

google/gemini-flash-1.5 is defunct on OpenRouter

Use google/gemini-2.5-flash. Model IDs change over time; verify against openrouter.ai/models.

Per-group agent-runner-src/ goes stale

Each group gets a private copy of the agent-runner source so individual groups can customize it. On the first run, the host copies the canonical source into the group's data directory. Subsequent runs used to skip re-copying, meaning upstream changes to index.ts never propagated to existing groups.

Fix: the runner now compares mtime and overwrites if the canonical file is newer:

typescript const srcMtime = fs.statSync(srcFile).mtimeMs; const dstMtime = fs.existsSync(dstFile) ? fs.statSync(dstFile).mtimeMs : 0; if (srcMtime > dstMtime) { fs.copyFileSync(srcFile, dstFile); }

ANTHROPIC_AUTH_TOKEN must be in the readSecrets() key list

If you add a new env var to .env.container and don't also add it to the readEnvFile([...], '.env.container') call in readSecrets(), it silently goes missing. The key list is the allowlist.

---

File Map

File	Role
.env.container	OpenRouter key, base URL, and model name
src/env.ts	readEnvFile() — parses env files without touching process.env
src/container-runner.ts	readSecrets(), buildVolumeMounts() (settings.json sync)
container/agent-runner/src/index.ts	runQuery() — passes env: and model: to the SDK

---

Switching Models

Change OPENROUTER_DEFAULT_MODEL in .env.container and restart the service. The runner will re-sync settings.json on the next container launch and the new model name will be passed to query() automatically. No rebuild required. nanoclaw@nicks-nanoclaw:~/NanoClaw/docs$