codeclaw

English | 中文

Control your local AI coding agents from any chat app. Anywhere, anytime.

codeclaw bridges AI coding assistants running on your dev machine to the messaging platforms you already use — so you can review code on the subway, kick off tasks from your phone, or pair-program from bed.

 You (Phone / Laptop / Tablet)
│
┌───────────────┼───────────────┐
▼ ▼ ▼
Feishu Slack Telegram ...8 platforms
│ │ │
└───────────────┼───────────────┘
▼
┌────────────┐
│ codeclaw │ ← your dev machine
└────────────┘
┌─────┼─────┐
▼ ▼ ▼
Claude Gemini Codex ...6 agents
Code CLI OpenCode

Why codeclaw?

Time to uninstall OpenClaw — codeclaw gives you access to the most powerful coding agents available, not just one.

6 AI Agents — Claude Code, Codex, Cursor Agent, Qoder CLI, Gemini CLI, OpenCode. Use whichever fits your workflow, or all of them at once.
8 Chat Platforms — Feishu, DingTalk, Slack, Telegram, Discord, WeChat Work, LINE, QQ. Most need zero public IP.
Full Control from Chat — Switch models (/model), change permission modes (/mode), manage sessions, all via slash commands.
Agent Memory — Read and write agent instruction files (/memory) without touching the terminal.
Scheduled Tasks — Set up cron jobs in natural language. "Every day at 6am, summarize GitHub trending" just works.
Voice & Images — Send voice messages or screenshots; codeclaw handles STT and multimodal forwarding.
Multi-Project — One process, multiple projects, each with its own agent + platform combo.

Support Matrix

Component	Type	Status
Agent	Claude Code	✅ Supported
Agent	Codex (OpenAI)	✅ Supported
Agent	Cursor Agent	✅ Supported
Agent	Gemini CLI (Google)	✅ Supported
Agent	Qoder CLI	✅ Supported
Agent	OpenCode	✅ Supported
Agent	Crush	🔜 Planned
Agent	Goose (Block)	🔜 Planned
Agent	Aider	🔜 Planned
Agent	Kimi Code (Moonshot)	🔭 Exploring
Agent	GLM Code / CodeGeeX (ZhipuAI)	🔭 Exploring
Agent	MiniMax Code	🔭 Exploring
Platform	Feishu (Lark)	✅ WebSocket — no public IP needed
Platform	DingTalk	✅ Stream — no public IP needed
Platform	Telegram	✅ Long Polling — no public IP needed
Platform	Slack	✅ Socket Mode — no public IP needed
Platform	Discord	✅ Gateway — no public IP needed
Platform	LINE	✅ Webhook — public URL required
Platform	WeChat Work (企业微信)	✅ Webhook — public URL required
Platform	QQ (via NapCat/OneBot)	✅ WebSocket, no public IP needed
Platform	WhatsApp	🔜 Planned (Business Cloud API)
Platform	Microsoft Teams	🔜 Planned (Bot Framework)
Platform	Google Chat	🔜 Planned (Chat API)
Platform	Mattermost	🔜 Planned (Webhook + Bot)
Platform	Matrix (Element)	🔜 Planned (Client-Server API)
Feature	Voice Messages (STT)	✅ Whisper API (OpenAI / Groq) + ffmpeg
Feature	Image Messages	✅ Multimodal (Claude Code)
Feature	API Provider Management	✅ Runtime provider switching
Feature	CLI Send (`codeclaw send`)	✅ Send messages to sessions via CLI

Quick Start

Prerequisites

Claude Code: Claude Code CLI installed and configured, OR
Codex: Codex CLI installed (npm install -g @openai/codex), OR
Cursor Agent: Cursor Agent CLI installed (agent --version to verify), OR
Gemini CLI: Gemini CLI installed (npm install -g @google/gemini-cli), OR
Qoder CLI: Qoder CLI installed (curl -fsSL https://qoder.com/install | bash), OR
OpenCode: OpenCode installed (opencode --version to verify)

Install & Configure via AI Agent (Recommended)

Send this to Claude Code or any AI coding agent, and it will handle the entire installation and configuration for you:

Please refer to https://raw.githubusercontent.com/cv70/codeclaw/refs/heads/main/INSTALL.md to help me install and configure codeclaw

Manual Install

Via npm:

npm install -g codeclaw

Download binary from GitHub Releases:

# Linux amd64
curl -L -o codeclaw https://github.com/cv70/codeclaw/releases/latest/download/codeclaw-linux-amd64
chmod +x codeclaw
sudo mv codeclaw /usr/local/bin/

Build from source (requires Go 1.22+):

git clone https://github.com/cv70/codeclaw.git
cd codeclaw
make build

Configure

# Global config (recommended)
mkdir -p ~/.codeclaw
cp config.example.yaml ~/.codeclaw/config.yaml
vim ~/.codeclaw/config.yaml
# Or local config (also supported)
cp config.example.yaml config.yaml

Run

./codeclaw # auto: ./config.yaml → ~/.codeclaw/config.yaml
./codeclaw -config /path/to/config.yaml # explicit path
./codeclaw --version # show version info

Upgrade

# npm
npm install -g codeclaw
# Binary self-update
codeclaw update
codeclaw update --pre

Platform Setup Guides

Each platform requires creating a bot/app on the platform's developer console. We provide detailed step-by-step guides:

Platform	Guide	Connection	Public IP?
Feishu (Lark)	docs/feishu.md	WebSocket	No
DingTalk	docs/dingtalk.md	Stream	No
Telegram	docs/telegram.md	Long Polling	No
Slack	docs/slack.md	Socket Mode	No
Discord	docs/discord.md	Gateway	No
LINE	INSTALL.md	Webhook	Yes
WeChat Work	docs/wecom.md	Webhook	Yes
QQ (NapCat)	docs/qq.md	WebSocket (OneBot v11)	No

Quick config examples for each platform:

# Feishuprojects:
- name: "my-project"platforms:
- type: "feishu"options:
app_id: "cli_xxxx"app_secret: "xxxx"# DingTalk
- type: "dingtalk"options:
client_id: "dingxxxx"client_secret: "xxxx"# Telegram
- type: "telegram"options:
token: "123456:ABC-xxx"# Slack
- type: "slack"options:
bot_token: "xoxb-xxx"app_token: "xapp-xxx"# Discord
- type: "discord"options:
token: "your-discord-bot-token"# LINE (requires public URL)
- type: "line"options:
channel_secret: "xxx"channel_token: "xxx"port: "8080"# WeChat Work (requires public URL)
- type: "wecom"options:
corp_id: "wwxxx"corp_secret: "xxx"agent_id: "1000002"callback_token: "xxx"callback_aes_key: "xxx"port: "8081"enable_markdown: false # true only if all users use WeChat Work app (not personal WeChat)# QQ (via NapCat/OneBot v11, no public IP needed)
- type: "qq"options:
ws_url: "ws://127.0.0.1:3001"allow_from: "*"# QQ user IDs, e.g. "12345,67890" or "*" for all

Permission Modes

All agents support permission modes switchable at runtime via /mode.

Claude Code modes (maps to --permission-mode):

Mode	Config Value	Behavior
Default	`default`	Every tool call requires user approval.
Accept Edits	`acceptEdits` (alias: `edit`)	File edit tools auto-approved; other tools still ask.
Plan Mode	`plan`	Claude only plans — no execution until you approve.
YOLO	`bypassPermissions` (alias: `yolo`)	All tool calls auto-approved. For trusted/sandboxed environments.

Codex modes (maps to --ask-for-approval):

Mode	Config Value	Behavior
Suggest	`suggest`	Only trusted commands (ls, cat...) run without approval.
Auto Edit	`auto-edit`	Model decides when to ask; sandbox-protected.
Full Auto	`full-auto`	Auto-approve with workspace sandbox. Recommended.
YOLO	`yolo`	Bypass all approvals and sandbox.

Cursor Agent modes (maps to --force / --mode):

Mode	Config Value	Behavior
Default	`default`	Trust workspace, ask before each tool use.
Force (YOLO)	`force` (alias: `yolo`)	Auto-approve all tool calls.
Plan	`plan`	Read-only analysis, no edits.
Ask	`ask`	Q&A style, read-only.

Gemini CLI modes (maps to -y / --approval-mode):

Mode	Config Value	Behavior
Default	`default`	Prompt for approval on each tool use.
Auto Edit	`auto_edit` (alias: `edit`)	Auto-approve edit tools, ask for others.
YOLO	`yolo`	Auto-approve all tool calls.
Plan	`plan`	Read-only plan mode, no execution.

Qoder CLI modes:

Mode	Config Value	Behavior
Default	`default`	Standard permissions; prompt for approval.
YOLO	`yolo`	Skip all permission checks, auto-approve.

OpenCode modes:

Mode	Config Value	Behavior
Default	`default`	Standard mode.
YOLO	`yolo`	Auto-approve all tool calls.

# Claude Codeprojects:
- name: "my-project"agent:
options:
mode: "default"# allowed_tools:# - "Read"# - "Grep"# - "Glob"# Codexagent:
options:
mode: "full-auto"# model: "o3"# Cursor Agentagent:
options:
mode: "default"# Gemini CLIagent:
options:
mode: "default"# Qoder CLIagent:
options:
mode: "default"# OpenCodeagent:
options:
mode: "default"

Switch mode at runtime from the chat:

/mode # show current mode and all available modes
/mode yolo # switch to YOLO mode
/mode default # switch back to default

API Provider Management

Switch between different API providers (e.g. Anthropic direct, relay services, AWS Bedrock) at runtime — no restart needed. Provider credentials are injected as environment variables into the agent subprocess, so your local config stays untouched.

Configure Providers

In config.yaml:

projects:
- name: "my-project"agent:
options:
work_dir: "/path/to/project"provider: "anthropic"# active provider nameproviders:
- name: "anthropic"api_key: "sk-ant-xxx"
- name: "relay"api_key: "sk-xxx"base_url: "https://api.relay-service.com"model: "claude-sonnet-4-20250514"# For special setups (Bedrock, Vertex, etc.), use the env map:
- name: "bedrock"env:
CLAUDE_CODE_USE_BEDROCK: "1"AWS_PROFILE: "bedrock"

Via CLI:

codeclaw provider add --project my-backend --name relay --api-key sk-xxx --base-url https://api.relay.com
codeclaw provider add --project my-backend --name bedrock --env CLAUDE_CODE_USE_BEDROCK=1,AWS_PROFILE=bedrock
codeclaw provider list --project my-backend
codeclaw provider remove --project my-backend --name relay

Import from cc-switch:

If you already use cc-switch to manage providers, import them with one command (requires sqlite3):

codeclaw provider import --project my-backend
codeclaw provider import --project my-backend --type claude # only Claude providers
codeclaw provider import --db-path ~/.cc-switch/cc-switch.db # explicit DB path

Manage Providers in Chat

/provider Show current active provider
/provider list List all configured providers
/provider add <name> <key> [url] [model] Add a provider
/provider add {"name":"relay","api_key":"sk-xxx","base_url":"https://..."}
/provider remove <name> Remove a provider
/provider switch <name> Switch to a provider
/provider <name> Shortcut for switch

Adding, removing, and switching providers all persist to config.yaml automatically. Switching restarts the agent session with the new credentials.

Env var mapping by agent type:

Agent	api_key →	base_url →
Claude Code	`ANTHROPIC_API_KEY`	`ANTHROPIC_BASE_URL`
Codex	`OPENAI_API_KEY`	`OPENAI_BASE_URL`
Gemini CLI	`GEMINI_API_KEY`	— (use `env` map)
OpenCode	`ANTHROPIC_API_KEY`	— (use `env` map)

The env map in provider config lets you set arbitrary environment variables for any setup (Bedrock, Vertex, Azure, custom proxies, etc.).

Claude Code Router Integration

Claude Code Router is a powerful tool that routes Claude Code requests to different model providers (OpenRouter, DeepSeek, Gemini, etc.) with custom transformations. codeclaw now supports seamless integration with Claude Code Router.

Why Use Claude Code Router?

Multi-Provider Support: Route requests to OpenRouter, DeepSeek, Ollama, Gemini, Volcengine, SiliconFlow, and more
Model Routing: Use different models for different tasks (background, thinking, long context, web search)
Request/Response Transformation: Automatic adaptation for different provider APIs
Dynamic Model Switching: Switch models on-the-fly without restarting

Setup

Install Claude Code Router:

npm install -g @musistudio/claude-code-router

Configure Router (create ~/.claude-code-router/config.json):

{
"APIKEY": "your-secret-key",
"Providers": [
{
"name": "openrouter",
"api_base_url": "https://openrouter.ai/api/v1/chat/completions",
"api_key": "sk-xxx",
"models": ["anthropic/claude-sonnet-4", "google/gemini-2.5-pro-preview"],
"transformer": { "use": ["openrouter"] }
},
{
"name": "deepseek",
"api_base_url": "https://api.deepseek.com/chat/completions",
"api_key": "sk-xxx",
"models": ["deepseek-chat", "deepseek-reasoner"],
"transformer": { "use": ["deepseek"] }
}
],
"Router": {
"default": "deepseek,deepseek-chat",
"think": "deepseek,deepseek-reasoner",
"longContext": "openrouter,google/gemini-2.5-pro-preview"
}
}

Start Router:

ccr start

Configure codeclaw (in config.yaml):

projects:
- name: "my-project"agent:
options:
work_dir: "/path/to/project"mode: "default"# Router integrationrouter_url: "http://127.0.0.1:3456"# Router URL (default port)router_api_key: "your-secret-key"# Optional: if router requires auth

How It Works

When router_url is configured, codeclaw automatically:

Sets ANTHROPIC_BASE_URL to the router URL
Sets NO_PROXY=127.0.0.1 to prevent proxy interference
Disables telemetry and cost warnings for cleaner integration

All Claude Code requests are then routed through the router, which handles model selection and provider communication.

Usage

Once configured, use codeclaw as usual. The router transparently handles model routing:

You: Help me refactor this code
Router → DeepSeek (default model)
You: Think through this architecture decision
Router → DeepSeek Reasoner (thinking model)
You: Analyze this large codebase
Router → Gemini Pro (long context model)

Important Notes

Provider settings are ignored: When using router, the projects.agent.providers settings are bypassed as the router manages model selection
Router must be running: Ensure ccr start is executed before starting codeclaw
Configuration changes: After modifying router config, restart with ccr restart

For more details, see the Claude Code Router documentation.

Voice Messages (Speech-to-Text)

Send voice messages directly — codeclaw transcribes them to text using a configurable STT provider, then forwards the text to the agent.

Supported platforms: Feishu, WeChat Work, Telegram, LINE, Discord, Slack

Prerequisites:

An API key for OpenAI or Groq (for Whisper STT)
ffmpeg installed (for audio format conversion — most platforms send AMR/OGG which Whisper doesn't accept directly)

Configure

speech:
enabled: trueprovider: "openai"# "openai" or "groq"language: ""# e.g. "zh", "en"; empty = auto-detectopenai:
api_key: "sk-xxx"# your OpenAI API key# base_url: "" # custom endpoint (optional, for OpenAI-compatible APIs)# model: "whisper-1" # default model# -- OR use Groq (faster and cheaper) --# groq:# api_key: "gsk_xxx"# model: "whisper-large-v3-turbo"

How It Works

User sends a voice message on any supported platform
codeclaw downloads the audio from the platform
If the format needs conversion (AMR, OGG → MP3), ffmpeg handles it
Audio is sent to the Whisper API for transcription
Transcribed text is shown to the user and forwarded to the agent

Install ffmpeg

# Ubuntu / Debian
sudo apt install ffmpeg
# macOS
brew install ffmpeg
# Alpine
apk add ffmpeg

Scheduled Tasks (Cron)

Create scheduled tasks that run automatically — like daily code reviews, periodic trend summaries, or weekly reports. When a cron job fires, codeclaw sends the prompt to the agent in your chat session and delivers the result back to you.

Manage via Slash Commands

/cron List all cron jobs
/cron add <min> <hour> <day> <mon> <wk> <prompt> Create a cron job
/cron del <id> Delete a cron job
/cron enable <id> Enable a job
/cron disable <id> Disable a job

Example:

/cron add 0 6 * * * Collect GitHub trending repos and send me a summary

Manage via CLI

codeclaw cron add --cron "0 6 * * *" --prompt "Summarize GitHub trending" --desc "Daily Trending"
codeclaw cron list
codeclaw cron del <job-id>

Natural Language Scheduling (via Agent)

Claude Code supports this out of the box — just tell it in natural language:

"每天早上6点帮我总结 GitHub trending" "Every Monday at 9am, generate a weekly status report"

Claude Code will automatically translate your request into a codeclaw cron add command via --append-system-prompt.

For other agents (Codex, Cursor, Gemini CLI), you need to add instructions to the agent's project-level instruction file so it knows how to create cron jobs. Add the following content to the corresponding file in your project root:

Agent	Instruction File
Codex	`AGENTS.md`
Cursor	`.cursorrules`
Qoder CLI	`AGENTS.md` (project), `~/.qoder/AGENTS.md` (global)
Gemini CLI	`GEMINI.md`
OpenCode	`OPENCODE.md`

Content to add:

# codeclaw Integration
This project is managed via codeclaw, a bridge to messaging platforms.
## Scheduled tasks (cron)
When the user asks you to do something on a schedule (e.g. "every day at 6am",
"every Monday morning"), use the Bash/shell tool to run:
codeclaw cron add --cron "<min> <hour> <day> <month> <weekday>" --prompt "<taskdescription>" --desc "<shortlabel>"
Environment variables CC_PROJECT and CC_SESSION_KEY are already set — do NOT
specify --project or --session-key.
Examples:
codeclaw cron add --cron "0 6 * * *" --prompt "Collect GitHub trending repos and send a summary" --desc "Daily GitHub Trending"
codeclaw cron add --cron "0 9 * * 1" --prompt "Generate a weekly project status report" --desc "Weekly Report"
To list or delete cron jobs:
codeclaw cron list
codeclaw cron del <job-id>
## Send message to current chat
To proactively send a message back to the user's chat session (use --stdin heredoc for long/multi-line messages):
codeclaw send --stdin <<'CCEOF'
your message here (any special characters are safe)
CCEOF
For short single-line messages:
codeclaw send -m "short message"

Daemon Mode

Run codeclaw as a background service managed by the OS init system (Linux systemd user service, macOS launchd LaunchAgent).

codeclaw daemon install --config ~/.codeclaw/config.yaml # install service
codeclaw daemon start
codeclaw daemon stop
codeclaw daemon restart
codeclaw daemon status
codeclaw daemon logs [-f] [-n N] [--log-file PATH]
codeclaw daemon uninstall

Install flags:--log-file PATH, --log-max-size N (MB), --work-dir DIR, --force. Logs auto-rotate at the size limit and keep one backup.

Session Management

Each user gets an independent session with full conversation context. Manage sessions via slash commands:

/new [name] Start a new session
/list List all agent sessions for this project
/switch <id> Switch to a different session
/current Show current session info
/history [n] Show last n messages (default 10)
/provider [...] Manage API providers (list/add/remove/switch)
/allow <tool> Pre-allow a tool (takes effect on next session)
/mode [name] View or switch permission mode
/quiet Toggle thinking/tool progress messages
/stop Stop current execution
/help Show available commands

During a session, the agent may request tool permissions. Reply allow / deny / allow all (auto-approve all remaining requests this session).

Configuration

Each projects[] entry binds one code directory to its own agent and platforms. A single codeclaw process can manage multiple projects simultaneously.

# Project 1projects:
- name: "my-backend"agent:
type: "claudecode"options:
work_dir: "/path/to/backend"mode: "default"platforms:
- type: "feishu"options:
app_id: "cli_xxxx"app_secret: "xxxx"# Project 2 — Codex agent with Telegram
- name: "my-frontend"agent:
type: "codex"options:
work_dir: "/path/to/frontend"mode: "full-auto"platforms:
- type: "telegram"options:
token: "xxxx"

See config.example.yaml for a fully commented configuration template.

Extending

Adding a New Platform

Implement the core.Platform interface and register it:

package myplatform
import"github.com/cv70/codeclaw/core"funcinit() {
core.RegisterPlatform("myplatform", New)
}
funcNew(optsmap[string]any) (core.Platform, error) {
return&MyPlatform{}, nil
}
// Implement Name(), Start(), Reply(), Send(), Stop()

Then add a blank import in cmd/main.go:

_"github.com/cv70/codeclaw/platform/myplatform"

Adding a New Agent

Same pattern — implement core.Agent and register via core.RegisterAgent.

Project Structure

codeclaw/
├── cmd/ # Entrypoint
│ └── main.go
├── core/ # Core abstractions
│ ├── interfaces.go # Platform + Agent interfaces
│ ├── registry.go # Plugin-style factory registry
│ ├── message.go # Unified message / event types
│ ├── session.go # Multi-session management
│ ├── i18n.go # Internationalization (en/zh)
│ ├── speech.go # Speech-to-text (Whisper API + ffmpeg)
│ └── engine.go # Routing engine + slash commands
├── platform/ # Platform adapters
│ ├── feishu/ # Feishu / Lark (WebSocket)
│ ├── dingtalk/ # DingTalk (Stream)
│ ├── telegram/ # Telegram (Long Polling)
│ ├── slack/ # Slack (Socket Mode)
│ ├── discord/ # Discord (Gateway WebSocket)
│ ├── line/ # LINE (HTTP Webhook)
│ ├── wecom/ # WeChat Work (HTTP Webhook)
│ └── qq/ # QQ (NapCat / OneBot v11 WebSocket)
├── agent/ # Agent adapters
│ ├── claudecode/ # Claude Code CLI (interactive sessions)
│ ├── codex/ # OpenAI Codex CLI (exec --json)
│ ├── cursor/ # Cursor Agent CLI (--print stream-json)
│ ├── qoder/ # Qoder CLI (-p -f stream-json)
│ ├── gemini/ # Gemini CLI (-p --output-format stream-json)
│ └── opencode/ # OpenCode (run --format json)
├── docs/ # Platform setup guides
├── config.example.yaml # Config template
├── INSTALL.md # AI-agent-friendly install guide
├── Makefile
└── README.md

License

MIT

Name		Name	Last commit message	Last commit date
.github/ISSUE_TEMPLATE		.github/ISSUE_TEMPLATE
agent		agent
cmd		cmd
config		config
core		core
daemon		daemon
docs		docs
npm		npm
platform		platform
.gitignore		.gitignore
INSTALL.md		INSTALL.md
Makefile		Makefile
README.md		README.md
README.zh-CN.md		README.zh-CN.md
config.example.yaml		config.example.yaml
go.mod		go.mod
go.sum		go.sum

Latest commit

History

Folders and files

Repository files navigation

codeclaw

Why codeclaw?

Support Matrix

Quick Start

Prerequisites

Install & Configure via AI Agent (Recommended)

Manual Install

Configure

Run

Upgrade

Platform Setup Guides

Permission Modes

API Provider Management

Configure Providers

Manage Providers in Chat

Claude Code Router Integration

Why Use Claude Code Router?

Setup

How It Works

Usage

Important Notes

Voice Messages (Speech-to-Text)

Configure

How It Works

Install ffmpeg

Scheduled Tasks (Cron)

Manage via Slash Commands

Manage via CLI

Natural Language Scheduling (via Agent)

Daemon Mode

Session Management

Configuration

Extending

Adding a New Platform

Adding a New Agent

Project Structure

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages