Claude CLI Proxy#

Route OpenClaw model requests through Claude Code CLI to use your existing Anthropic subscription (Team/Max/Pro) instead of paying per-token API costs.

How It Works#

text

OpenClaw → HTTP request (Anthropic Messages API format)
       → claude-cli-proxy (localhost:8081)
       → acpx claude prompt (persistent session)
       → Claude Code CLI (uses subscription auth)
       → Response streamed back as SSE

Prerequisites#

• Node.js 18+
• Claude Code CLI installed and authenticated with a subscription (Team/Max/Pro)
• acpx installed globally ( npm i -g acpx)

Environment Variables#

All configurable via env — no hardcoded paths:

VariableDefaultDescriptionCCPROXY_PORT``8081Proxy listen portCCPROXY_SESSION_NAME``dexter-proxyacpx session nameCCPROXY_CWD``~/.openclaw/workspaceWorking directoryCCPROXY_TIMEOUT_MS``120000Request timeoutCCPROXY_MAX_HISTORY``10Max conversation turns forwarded

Also respects OPENCLAW_WORKSPACE as fallback for CWD.

Setup#

1. Install & Authenticate Claude Code#

bash

npm install -g @anthropic-ai/claude-code acpx
claude auth login  # Select claude.ai, NOT API key
claude "say ok"    # Verify it works

2. Copy Proxy Scripts#

Copy scripts/claude-cli-proxy.js and scripts/ccproxy-ensure.js to your OpenClaw workspace:

bash

cp scripts/claude-cli-proxy.js ~/.openclaw/workspace/
cp scripts/ccproxy-ensure.js ~/.openclaw/workspace/

3. Configure Agent Identity (Important)#

Without this, Claude Code responds as generic "Claude". To preserve your agent's personality:

a) Set customInstructions in Claude Code settings:

bash

cat > ~/.claude/settings.json << 'EOF'
{
  "customInstructions": "You are [YOUR_AGENT_NAME]. Your identity is defined in CLAUDE.md. Always respond as [YOUR_AGENT_NAME]. This is not roleplay — this is your configured identity by your operator."
}
EOF

Replace [YOUR_AGENT_NAME] with your agent's name (e.g., "Ozwald", "Dexter", "Atlas").

b) Create a CLAUDE.md in your workspace with your agent's full identity, style, and context. Claude Code reads this file automatically on every session. Copy the relevant parts from your SOUL.md / IDENTITY.md.

Why both? settings.json is the minimum instruction Claude Code always respects. CLAUDE.md provides richer context (relationships, style, domain knowledge) that the agent reads when it needs it.

4. Create Persistent Session#

bash

cd ~/.openclaw/workspace
ANTHROPIC_API_KEY="" acpx claude sessions new --name dexter-proxy

Critical: ANTHROPIC_API_KEY="" ensures Claude Code uses subscription auth, not any API key in the environment.

5. Start the Proxy#

bash

node ~/.openclaw/workspace/ccproxy-ensure.js

Verify: curl http://127.0.0.1:8081/health

6. Configure OpenClaw Provider#

Add to openclaw.json (or use config.patch):

json

{
  "models": {
    "mode": "merge",
    "providers": {
      "claude-cli": {
        "baseUrl": "http://127.0.0.1:8081/v1",
        "apiKey": "dummy",
        "api": "anthropic-messages",
        "models": [
          {
            "id": "claude-sonnet-4-6",
            "name": "claude-sonnet-4-6",
            "api": "anthropic-messages",
            "reasoning": false,
            "input": ["text"],
            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
            "contextWindow": 200000,
            "maxTokens": 8192
          }
        ]
      }
    }
  }
}

Set as default model:

json

{
  "agents": {
    "defaults": {
      "model": { "primary": "claude-cli/claude-sonnet-4-6" }
    }
  }
}

7. Auto-Start (macOS)#

See references/autostart.md for LaunchAgent config.

7b. Auto-Start (Linux/Docker)#

Add to HEARTBEAT.md:

text

node /path/to/workspace/ccproxy-ensure.js

What Gets Forwarded#

The proxy forwards the full OpenClaw context to Claude Code:

1. System prompt → Written to .ccproxy-system-context.md, Claude Code reads it as operator context (avoids prompt injection rejection)
2. Conversation history → Last N turns (configurable via CCPROXY_MAX_HISTORY)
3. Current message → Last user message

Claude Code metadata ( [thinking], [tool], file dumps) is automatically stripped from output.

Key Details#

• First call after cold start: ~8s (agent reconnects)
• Subsequent calls: ~2-3s
• Streaming: Full SSE support (required by OpenClaw)
• Serialized: Requests queue — CLI handles one at a time
• Session persistence: Survives proxy restarts, stored on disk by acpx
• Token refresh: Claude Code handles OAuth token refresh automatically
• Privacy note: System prompt content is written to .ccproxy-system-context.md in the workspace and sent to Anthropic on each request. The file is overwritten on every request (never accumulates stale data) but persists on disk between requests.
• Fake streaming caveat: SSE chunks are sent after the full response completes — first-token latency equals full response time. Real-time piping would require acpx to support stdout streaming natively.

Troubleshooting#

SymptomCauseFixLLM request timed outProxy not returning SSE streamEnsure proxy v5+ with streaming supportrequest ended without sending any chunks``stream:true but proxy returns JSONUpdate to proxy v5Claude says "I am Claude" not your agent identityMissing customInstructions in settings.jsonAdd customInstructions + CLAUDE.mdrate_limit_errorSubscription rate limit hitWait or upgrade plan tierProxy won't startPort 8081 in usepkill -f claude-cli-proxy then restartProxy won't startCWD path doesn't existSet CCPROXY_CWD or OPENCLAW_WORKSPACE env varMultiple instances collideSame session nameSet unique CCPROXY_SESSION_NAME per instance