openclaw-claude-code-bridge

OpenClaw plugin that routes Anthropic LLM requests through the local Claude Code CLI subprocess, using your Claude Pro/Max subscription.

Instead of forging API requests (which Anthropic detects), this plugin spawns the real claude CLI binary. The CLI handles all authentication, billing, and request signing natively.

How It Works

OpenClaw request
  → Plugin intercepts via wrapStreamFn
  → Spawns `claude --print --input-format stream-json` subprocess
  → CLI handles auth/billing/signing
  → Converts CLI stream-json output to Anthropic SSE
  → Returns to OpenClaw as standard stream

The CLI is invoked with --dangerously-skip-permissions, which lets the model use Claude Code CLI's built-in tools (Read/Write/Edit/Bash/Glob/Grep/WebFetch/etc.) without permission prompts. This is required for OpenClaw agents to work properly — the model maps OpenClaw's tool descriptions in the system prompt to CLI's matching built-in tools and executes them in the subprocess context.

Prerequisites

• OpenClaw gateway installed
• Claude Code CLI installed and authenticated
• Claude Pro or Max subscription

Verify CLI works:

claude --version
claude -p "say hi"

Installation

Option A: Install from npm (recommended)

npm install -g openclaw-claude-code-bridge

The package ships with prebuilt dist/, so no build step is needed. Then point your OpenClaw config at the global install path (the global node_modules location depends on your Node setup — find it via npm root -g).

Option B: Clone from source

git clone https://github.com/SeaL773/openclaw-claude-code-bridge.git
cd openclaw-claude-code-bridge
npm install
npm run build

Configure OpenClaw

Edit your OpenClaw config:

• Windows: C:\Users\<user>\.openclaw\openclaw.json
• macOS/Linux: ~/.openclaw/openclaw.json

Add the plugin to the plugins section:

{
  "plugins": {
    // disable OpenClaw's built-in Anthropic provider so this bridge takes over
    "deny": ["anthropic"],
    "load": {
      "paths": ["/absolute/path/to/openclaw-claude-code-bridge/dist"]
    },
    "entries": {
      "openclaw-claude-code-bridge": {
        "enabled": true
      }
    }
  }
}

Use the absolute path to the dist/ directory. If installed via npm, this is typically <npm-root>/openclaw-claude-code-bridge/dist where <npm-root> comes from npm root -g.

Set up auth profile

{
  "auth": {
    "profiles": {
      "anthropic:default": {
        "provider": "anthropic",
        "mode": "token"
      }
    }
  }
}

The plugin reads OAuth tokens from your Claude CLI keychain automatically — no token paste required.

Restart OpenClaw

Look for these log lines to confirm it works:

[claude-bridge] plugin loaded, registering provider: anthropic
[claude-bridge] prepareRuntimeAuth: using stored OAuth token (sk-ant-oat…)
[claude-bridge] wrapStreamFn: intercepting request → CLI subprocess, model: claude-opus-4-6
[claude-bridge] spawning CLI: claude --model claude-opus-4-6

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | CLAUDE_BIN | claude | Path to Claude CLI binary | | CLAUDE_MAX_CONCURRENT | 2 | Max concurrent CLI subprocesses | | CLAUDE_TIMEOUT_MS | 300000 | Per-request timeout (5 min default) |

Limitations

• OpenClaw's structured tool protocol is not preserved. OpenClaw's tools definition in the request body is dropped on the floor. The model improvises by mapping OpenClaw's tool descriptions (which it sees in the flattened system prompt text) to Claude Code CLI's built-in tools (Read/Write/Edit/Bash/Glob/Grep/WebFetch/...). This usually works for common file/shell operations but won't work for OpenClaw-specific tools (e.g. cron, message, custom skills) unless the model can simulate them via Bash + curl or similar primitives.
• Tool results come back as text, not as structured tool_use / tool_result blocks. OpenClaw's "tool call breakdown" UI won't populate.
• Streaming is block-level (per content block from CLI), not token-by-token.
• Conversation history is flattened to plain text (Human: ... Assistant: ...) — tool_use / tool_result / thinking blocks in history are converted to text descriptions.

Troubleshooting

Persistent API Error: 400 You're out of extra usage even though your quota isn't depleted

This is caused by a Claude CLI safety mechanism: when the conversation history contains previous assistant turns with bridge error messages (e.g. from a one-off CLI crash), the CLI detects the pattern and short-circuits with a synthetic error response without calling the API. You can identify this case in the CLI's session log at ~/.claude/projects/<cwd-slug>/<sid>.jsonl — the response will have "model":"<synthetic>" and duration_api_ms:0.

v1.1.3+ filters these poisoned messages out automatically via BRIDGE_ERROR_MARKERS in cli-bridge.ts. If you still see this issue, clear the session's conversation history in the OpenClaw UI (or start a new session).

Security

⚠️ The bridge runs Claude Code CLI with --dangerously-skip-permissions.

This is required for OpenClaw agents to function — the model needs access to file/shell tools to execute the user's tasks. As a consequence:

• The CLI subprocess inherits the OpenClaw gateway's process context (cwd, env, file permissions, network access).
• Any prompt that reaches the bridge (including content from web fetches, user messages, automated pipelines, agent loops) can cause the model to use Read/Write/Bash/etc. on the gateway's machine.
• Do not deploy the bridge behind any interface that accepts untrusted prompts. This is a personal-automation tool, not a multi-tenant gateway.

If you need a sandboxed bridge (no tool execution at all), pin to v1.1.6 — but expect that OpenClaw agents requiring tools will fail.

Credits

• Inspired by opencode-claude-bridge
• CLI subprocess approach from shinglokto/openclaw-claude-bridge

License

MIT