English | 中文

Openclaw Catch Claude Code

The lobster shakes hands with Claude — small models command big models to do the work.

Punching above its weight: unlock the full power of OpenClaw and Claude Code at minimal cost.

Anthropic has restricted OpenClaw from using Claude subscriptions directly, and API calls are expensive. Our approach: use any cheap small model (GPT-mini, Gemini Flash, or even local Ollama) as a secretary on OpenClaw, dispatching tasks to Claude Code CLI — powered by the user’s own CLI subscription. The secretary is cheap, the worker is powerful — that’s how a small horse pulls a big cart.

A humble contribution to the open-source AI movement.

Core Motivation

Anthropic restricted OpenClaw from using Claude subscriptions — a significant blow to the lobster community. Calling the Claude API directly is painfully expensive.

But Claude Code CLI is an independent product — users subscribe and use it normally, unrelated to OpenClaw.

We found a way: skip the API, use the CLI. Secretary runs on a small model, the real work runs on Claude.

Traditional (expensive):  OpenClaw → Claude API      → every message burns money
Our approach (cheap):     OpenClaw → small model (nearly free) → Claude Code CLI (user's own subscription)

Core Features

• Multi-CLI pool – 3 specialized agents (general / code / complex), each an independent Claude Code CLI process
• Per-agent model selection – general defaults to Sonnet (fast + cheap), code/complex default to Opus (powerful); configurable via env vars and API params for flexible cost/performance control
• Per-agent workspaces – .cli-workspaces/{name}/ with full .claude/ customization (CLAUDE.md, settings.json, rules, subagents)
• Structured output routing – [routing: general|code|complex] tags drive automatic dispatch, works with any model
• OpenClaw integration – HTTP-to-CLI bridge + Telegram via hooks
• Custom scheduled tasks – cron / interval / one-shot scheduling
• Fully customize your lobster – OpenClaw’s SOUL.md, AGENTS.md, BOOTSTRAP.md, Skills, and Hooks are all open for customization — build your own AI assistant personality and workflow
• Pluggable 3-layer architecture – Secretary (classify) → CLI (execute) → Personal OpenClaw (polish). Each layer is independent and replaceable. CLI results can be routed to your own personalized OpenClaw instance for post-processing (summarize, translate, style) before reaching the user
• Session persistence – atomic writes + schema validation + token usage tracking
• 138 tests, zero external dependencies – Node.js 18+ built-in APIs only
• Zero ban risk

Project Structure

server.js                     -- Entry point (delegates to src/server.js)
src/
  server.js                   -- HTTP server, routing, auth, CORS
  routes/
    cli.js                    -- CLI pool endpoints (/cli/*)
    task.js                   -- Task management endpoints (/task/*, /tasks/*, /lead/*)
    session.js                -- Named session endpoints (/session/*)
    claude.js                 -- Claude CLI endpoints (/connect, /sessions, /resume, etc.)
    tools.js                  -- Direct tool endpoints (/bash, /read, /call, /batch-read)
  lib/
    cli-pool.js               -- Multi-CLI pool (general/code/complex)
    claude-runner.js           -- Claude CLI process management, SSE streaming, concurrency
    session-store.js           -- Session persistence (atomic writes, schema validation)
    task-store.js              -- Task state persistence
    helpers.js                 -- JSON response, body parsing, CLI arg building
    logger.js                  -- Structured logging (controlled by LOG_LEVEL)
openclaw/
  docker-compose.yml           -- OpenClaw deployment config
  openclaw.json.example        -- OpenClaw config template
  AGENTS.md                    -- Agent role definitions
  SKILL.md                     -- Skill configuration
  BOOTSTRAP.md                 -- Bootstrap prompt
  hooks/cli-router/            -- Message routing hook
  mcp/                         -- HTTP-to-CLI bridge config
  claude_setting_example/      -- .claude/ config examples for all 3 agents
test/
  helpers.test.js              -- Helper utility unit tests
  server.test.js               -- HTTP endpoint integration tests
  lead-agent.test.js           -- Lead agent / task routing tests
  cli-pool.test.js             -- CLI pool tests
  fake-claude.js               -- Claude CLI mock for testing
docs/
  openapi.yaml                 -- OpenAPI 3.0 spec
  cron-guide.md                -- Scheduled tasks guide

Quick Start

Prerequisites

• Node.js 18+
• Claude Code CLI installed and authenticated

Install and run

git clone https://github.com/samwalter2949348803-stack/Openclaw-catch-Claude-Code.git
cd Openclaw-catch-Claude-Code
node server.js

Server listens on http://127.0.0.1:18795 (localhost only).

Environment Variables

API Endpoints

All endpoints (except /health) are prefixed with /backend-api/claude-code.

Example: POST http://localhost:18795/backend-api/claude-code/cli/send

Health Check

CLI Management

Task Management

Session Management

Tools

Connection

CLI Agent Workspaces

Each CLI agent (general, code, complex) can have its own workspace at .cli-workspaces/{name}/. When a CLI starts, the harness automatically detects the directory and uses it as the working directory.

A workspace can contain:

• CLAUDE.md – agent-specific project instructions
• .claude/settings.json – local config and hooks
• .claude/rules/ – additional rule files
• .claude/agents/ – subagent definitions

See openclaw/claude_setting_example/README.md for complete examples of all three agent configurations.

OpenClaw Integration

OpenClaw is the external orchestration layer that connects Telegram users to this harness.

• Hooks – The message:sent hook in openclaw/hooks/cli-router/ intercepts messages with [routing: agent] tags and forwards them to the corresponding CLI endpoint
• Telegram – Users interact via Telegram; OpenClaw classifies messages and tags them for routing
• Config – See openclaw/docker-compose.yml and openclaw/openclaw.json.example for deployment setup
• Agent roles – See openclaw/AGENTS.md for role definitions
• Skills – See openclaw/SKILL.md for skill configuration
• Bootstrap – See openclaw/BOOTSTRAP.md for initialization flow

Scheduled Tasks

OpenClaw’s built-in cron scheduler supports three scheduling modes:

• Cron expressions – --cron "0 10 * * *" for precise scheduling
• Fixed intervals – --every "30m" for periodic checks
• One-shot – --at "5m" for delayed execution

Results can be pushed to Telegram. Messages containing [routing: xxx] tags are automatically dispatched to the corresponding CLI agent.

Full configuration guide: openclaw/cron-guide.md.

How It Works (30-second version)

1. You send a message via Telegram
2. OpenClaw’s model classifies it: Processing your request... [routing: code] write unit tests
3. The message:sent hook intercepts the routing tag
4. The hook calls the harness API (POST /cli/send)
5. The harness dispatches to the code CLI agent
6. Claude Code CLI executes the task with full file system access
7. The result is sent back to you via Telegram Bot API

The model only classifies. The CLI does all the real work.

Testing

npm test

138 tests using Node.js built-in test runner (node --test). Includes a Claude CLI mock (test/fake-claude.js) — no real Claude environment needed to run tests.

Acknowledgments

• OpenClaw — bringing AI agents into everyone’s life
• Claude Code — Anthropic’s powerful coding CLI
• All developers contributing to the open-source AI ecosystem

License

MIT — free to use, modify, and distribute.

If this project helps you, consider giving it a star or submitting a PR to help improve it.