@a1hvdy/cc-openclaw

v0.34.0

Published

a month ago

A1xAI's Anthropic CLI bridge plugin for OpenClaw

0High
0Medium
0Low

a1xai

cc-openclaw

A1xAI's Claude Code → OpenAI-compatible HTTP bridge plugin for OpenClaw.

Routes claude CLI subprocess sessions through an OpenAI-compatible API at http://127.0.0.1:18796, enabling OpenClaw to use Claude Code as the inference backend for Telegram bots, MCP tooling, and multi-laptop session sync.

Quick start (one command)

bash <(curl -fsSL https://raw.githubusercontent.com/A1cy/cc-openclaw/main/scripts/bootstrap.sh)

The bootstrap script handles: prereq detection, openclaw binary install/upgrade, npm install of @a1hvdy/cc-openclaw via openclaw plugins install, env file configuration, interactive prompt for required secrets (Anthropic key, optional Telegram bot tokens), OpenRouter pricing-cache patch, openclaw doctor --fix, gateway restart, and smoke probes. Idempotent — safe to re-run.

Flags

--non-interactive — env-only secret resolution (no prompts)
--skip-tg-tokens — install without Telegram setup
--no-restart — skip the gateway restart (manual)
--from-source — clone+build from GitHub instead of npm (slower; for plugin development)

Features

Native Claude CLI Support — cc-openclaw passes through Claude Code's built-in commands:

Multi-turn goals (/goal <objective>) — Set execution conditions that persist across turns with automatic Haiku evaluation (Claude CLI 2.1.139+)
Session management (/new, /sessions, /cc) — Universal session compatibility
Tool streaming — Real-time tool call updates in Telegram cards
MCP bridge — OpenClaw native tools available in Claude Code sessions

Telegram Integration:

Live cards with status updates, tool results, and insights
Tool result deduplication (50-60% card size reduction)
Session listing optimization (10× faster)
Plan attachments and interactive buttons

Performance:

Subprocess pooling for faster cold starts
Cache parity optimization for reduced token costs
Chunked file reading for large session transcripts

See CHANGELOG.md for detailed feature documentation.

Prerequisites

Node.js ≥ 22
Anthropic API key
(Optional) Telegram bot token(s) from @BotFather
Linux/WSL2/macOS (tested on WSL2 Ubuntu 24)

Manual install

If you'd rather not run the bootstrap script:

# 1. OpenClaw binary
npm install -g openclaw@beta

# 2. Plugin install via openclaw CLI (npm registry)
openclaw plugins install --dangerously-force-unsafe-install --force \
  @a1hvdy/cc-openclaw

# 3. Required env vars in BOTH ~/.openclaw/.env AND ~/.openclaw/gateway.systemd.env
cat >> ~/.openclaw/.env <<EOF
ANTHROPIC_API_KEY=sk-ant-...
OPENCLAW_CC_OPENCLAW_LISTENERS=1
OPENCLAW_CC_OPENCLAW_ACTIVE=1
CC_OPENCLAW_ALLOW_BUILTINS=1
CC_OPENCLAW_TOOL_STREAM=1
UX_BRIDGE_ALL_SESSIONS=true
OPENCLAW_CACHE_PARITY=1
OPENCLAW_AGGRESSIVE_STRIP=1
EOF
cp ~/.openclaw/.env ~/.openclaw/gateway.systemd.env  # both files must mirror

# 4. Telegram bot tokens go in openclaw.json (see Configuration below)

# 5. Apply OpenRouter patch + run doctor
bash ~/dev/cc-openclaw/scripts/patch-openrouter.sh
openclaw doctor --fix

# 6. Restart gateway
pm2 restart openclaw-gateway --update-env

Configuration

Required env vars (in BOTH `.env` and `gateway.systemd.env`)

| Variable | Purpose | |---|---| | ANTHROPIC_API_KEY | Claude API authentication | | OPENCLAW_CC_OPENCLAW_LISTENERS=1 | Activate plugin event listeners | | OPENCLAW_CC_OPENCLAW_ACTIVE=1 | Set cc-openclaw as primary engine | | CC_OPENCLAW_ALLOW_BUILTINS=1 | Enable Claude Code built-in tools (WebFetch, WebSearch) | | CC_OPENCLAW_TOOL_STREAM=1 | Real-time tool-call streaming (v0.3.0+) | | UX_BRIDGE_ALL_SESSIONS=true | Live cards for every Telegram session | | OPENCLAW_CACHE_PARITY=1 | Track-B prompt cache parity | | OPENCLAW_AGGRESSIVE_STRIP=1 | Strip openclaw sysprompt artifacts |

Both files must mirror — pm2 reads gateway.systemd.env, savvyflow reads .env.

Optional env vars (v0.16+)

Dark-flagged features added in v0.16.0. Default behavior is unchanged when these are unset.

| Variable | Default | Effect when =1 | |---|---|---| | OPENCLAW_SUBPROCESS_POOL | off | Persistent claude subprocess pool with conv-boundary recycle. Cuts cold-turn latency. | | OPENCLAW_THINKING_SURFACE | off | Surface extended-thinking blocks as OpenAI-shaped delta.reasoning SSE chunks. thinking_block trajectory event emits regardless. |

If you maintain a custom heartbeat schedule, ensure heartbeat.model is set in openclaw.json — v0.16+ refuses unguarded heartbeats with an error referencing OpenClaw issues #9556 / #13009 / #14279.

Telegram bot tokens

Tokens live in ~/.openclaw/openclaw.json under channels.telegram.accounts[]:

{
  "channels": {
    "telegram": {
      "accounts": [
        { "id": "savvy-home", "botToken": "1234:ABC...", "label": "SavvyHomeBot" },
        { "id": "savvy-work", "botToken": "5678:XYZ...", "label": "SavvyWorkBot" }
      ]
    }
  }
}

The bootstrap.sh script writes these atomically via jq if you provide tokens during the interactive prompt. To add later, edit the JSON manually or use openclaw config set.

Verification

After install:

# Health probes
curl -s http://127.0.0.1:18790/health   # OpenClaw gateway
curl -s http://127.0.0.1:18796/health   # cc-openclaw embedded server

# Plugin loaded?
pm2 logs openclaw-gateway --lines 30 --nostream | grep cc-openclaw
# Expect: "cc-openclaw/index" register-guard.fire entries

In Telegram:

/new → ONE greeting (not doubled)
/cc what time is it? → live card, tool runs, summary lands
/status → model field shows cc-openclaw/... (NOT claude-local, NOT gpt-5.4)
/search anthropic → web search runs (confirms CC_OPENCLAW_ALLOW_BUILTINS=1)

Troubleshooting

"/status shows claude-local"

The route flag default. Means OPENCLAW_CC_OPENCLAW_ACTIVE=1 isn't in the gateway's env. Verify with:

pm2 env openclaw-gateway | grep OPENCLAW_CC_OPENCLAW

If missing: ensure it's in BOTH ~/.openclaw/.env AND ~/.openclaw/gateway.systemd.env, then pm2 restart openclaw-gateway --update-env.

"Gateway falls back to gpt-5.4"

Means cc-openclaw's :18796 server is unreachable. Check:

curl -s http://127.0.0.1:18796/health
ss -tln | grep 18796

If port 18796 isn't listening, the cwd-patch eager-server start failed — check pm2 logs openclaw-gateway --lines 50 for cc-openclaw errors.

"ENOENT: stubs/commands-status-deps.runtime.js"

Pre-0.3.1 bug. Update to ≥0.3.1 — the stub-path resolution was fixed to use marker-based walk-up instead of dirname(import.meta.url). Re-run bootstrap.sh or:

cd ~/dev/cc-openclaw && git pull && npm run build
bash ~/.openclaw/scripts/sync-cc-openclaw.sh

After upgrading openclaw binary

The OpenRouter pricing-cache patch must be re-applied (npm install wipes it):

bash ~/dev/cc-openclaw/scripts/patch-openrouter.sh
pm2 restart openclaw-gateway --update-env

Architecture

┌─ Telegram ──────────────────────────┐
│  Bot messages                        │
└──────────┬───────────────────────────┘
           │ openclaw-gateway :18790
           ▼
┌─ OpenClaw Gateway ──────────────────┐
│  - Routing / fallbacks               │
│  - Telegram channel adapter          │
│  - cc-openclaw plugin loaded         │
└──────────┬───────────────────────────┘
           │ HTTP /v1/chat/completions
           ▼
┌─ cc-openclaw embedded server :18796 ┐
│  - SessionManager (per-chat)         │
│  - SSE translator                    │
│  - claude CLI subprocess pool        │
└──────────┬───────────────────────────┘
           │ stdin/stdout NDJSON
           ▼
┌─ claude CLI subprocess ─────────────┐
│  - Anthropic Messages API            │
│  - tool_use blocks                   │
└──────────────────────────────────────┘

When the cc-openclaw chain fails (network, API quota, bug), OpenClaw falls through agents.list[main].model.fallbacks — typically ending at openai-codex/gpt-5.4 as a last-resort liveness fallback.

Internal docs

Project orchestration: ~/.openclaw/workspace/orchestration/projects/cc-openclaw/
Phase 4 PRP: ~/.openclaw/workspace/orchestration/projects/cc-openclaw-phase4/PRP_v1.md
Cross-laptop handoff: ~/.openclaw/handoff/