claude-code-bridge

Bridges OpenClaw (QQ, Telegram, WeChat, and other messaging channels) to a persistent Claude Code CLI session running in a background tmux process. Enables s...

Security Scan

The skill's code, instructions, and resource requests line up with its stated purpose (bridging chat messages to a local Claude Code CLI in a tmux session); there are no unexplained credential requests or remote downloads, but the bridge inherently exposes your local Claude session and filesystem to anyone who can send messages to the bridged chat, so use only in trusted chats or with sandbox mode.

Purpose & Capability

Name/description describe a tmux-based bridge to a local 'claude' CLI; the included script implements tmux session creation, send/approve/status/stop/restart/peek/history etc. There are no unrelated environment variables or external services requested. This set of requirements is coherent for the stated purpose.

Instruction Scope

SKILL.md and the script instruct the agent to forward every message to a local claude CLI running in tmux and to manage workdirs (including user-specified paths) and sandbox temp dirs. This is expected, but it means any forwarded chat message can cause the local Claude CLI to run actions (including invoking shell-mode or initiating file reads/writes via CC). The instructions do not attempt to read other unrelated system state beyond the skill's own state files in ~/.openclaw/claude-code-bridge.

Install Mechanism

No install spec or external downloads; this is an instruction-only skill with one shell script and docs. Nothing is fetched from arbitrary URLs and no archives are extracted.

Credentials

The skill requires no credentials or special env vars. It uses standard local paths (HOME, ~/.openclaw/*) and an optional CLAUDE_BIN override; these are proportional to running a local CLI bridge.

Persistence & Privilege

always is false and autonomous invocation is allowed by default (normal). The skill stores state under ~/.openclaw/claude-code-bridge and creates tmux sessions — appropriate for its function and not modifying other skills or system-wide configs.

Assessment

This skill is internally coherent, but it forwards chat text directly into a local interactive Claude CLI — which can execute commands, read/write files, and output file contents. Before installing: 1) Only enable/activate it for trusted chat channels (untrusted group chats could be used to run commands). 2) Prefer '沙盒' (sandbox) mode when experimenting; sandbox directories are created in /tmp and cleaned on stop. 3) Review the script (scripts/claude-code-bridge.sh) locally to confirm behavior and the default CLAUDE_BIN path, and consider running it in a restricted test account. 4) Be aware it writes logs and state to ~/.openclaw/claude-code-bridge and creates tmux sessions named ccb_<id>. 5) Note source/homepage unknown — if provenance is important, request the upstream repository or author and verify updates before trusting long-term.

Bridge every incoming message to a live, persistent claude CLI process running in a background tmux session. The user interacts via QQ/Telegram/any channel; Claude Code responds as if they were typing in a real terminal.

Session State Detection (CRITICAL — CHECK EVERY TURN)

At the start of EVERY incoming message, determine session state:

~/.openclaw/workspace/skills/claude-code-bridge/scripts/claude-code-bridge.sh "<SESSION_ID>" status

• ✅ Claude Code 会话运行中 → CC mode active, route message to CC
• ⭕ 没有活跃 → CC mode off, respond normally
• ⚠️ CC 正在等待审批 → tell user and await their approval choice

Construct <SESSION_ID> as <channel>_<chat_id> using only [a-zA-Z0-9_].

Routing Logic

Every incoming message:
  1. Run status check
  2. Is it a CC control command?
       ──── Startup (with workdir) ────
       "在 <path> 打开cc"        → start <path>
       "沙盒打开cc" / "沙盒模式" → start --sandbox
       "启动cc"（no path）       → ASK workdir first (see Startup Flow below)
       ──── Other controls ────
       "关闭cc"    → stop
       "重启cc"    → restart
       "cc状态"    → status
       "cc在哪" / "cc目录" → workdir
       "/cc peek"  → peek
       "/cc history [N]" → history
  3. Is CC in approval-waiting state?
       YES → parse user's intent (y/n/1/2/3) → approve
  4. Is CC session active?
       YES → forward as send
       NO  → respond normally as OpenClaw agent

Startup Flow — Working Directory

When the user wants to start Claude Code without specifying a directory:

1. Ask briefly: "工作目录放哪？发路径就在那里打开，不指定就用临时沙盒。"
2. Parse the reply:
   • User sends a path (e.g. ~/projects/paper) → start ~/projects/paper
   • User says "沙盒" / "随便" / "临时" / doesn't specify → start --sandbox

When the user specifies a directory in the startup command itself:

• "在 ~/Documents/Code 打开cc" → extract the path → start ~/Documents/Code
• "沙盒打开cc" / "沙盒模式启动cc" → start --sandbox

Do NOT ask if the path is already provided in the command.

Executing Actions

SCRIPT="$HOME/.openclaw/workspace/skills/claude-code-bridge/scripts/claude-code-bridge.sh"

"$SCRIPT" "<ID>" start '/path/to/workdir'   # 在指定目录启动
"$SCRIPT" "<ID>" start --sandbox             # 沙盒模式启动
"$SCRIPT" "<ID>" send '<message>'            # 发送（90s 超时）
"$SCRIPT" "<ID>" send '<message>' --long     # 长任务（5min 超时）
"$SCRIPT" "<ID>" approve 1                   # 审批：选 Yes
"$SCRIPT" "<ID>" approve 2                   # 审批：选 Allow always
"$SCRIPT" "<ID>" approve 3                   # 审批：选 No
"$SCRIPT" "<ID>" approve esc                 # 审批：取消
"$SCRIPT" "<ID>" stop                        # 停止（沙盒自动清理）
"$SCRIPT" "<ID>" restart                     # 重启（保留原工作目录）
"$SCRIPT" "<ID>" restart '/new/path'         # 重启到新目录
"$SCRIPT" "<ID>" status                      # 状态（含工作目录信息）
"$SCRIPT" "<ID>" workdir                     # 查询当前工作目录
"$SCRIPT" "<ID>" peek                        # 原始终端画面
"$SCRIPT" "<ID>" history 200                 # 最近 200 行历史

IMPORTANT — message quoting: Use tmux send-keys -l (literal mode) so special characters ($, !, \) are sent verbatim. The script handles this internally; just pass the raw message as argument 3.

CC Slash Commands — Direct Passthrough

CC's own slash commands work by sending them via send:

User says	Forward as
/plan	send '/plan'
/model sonnet	send '/model sonnet'
/compact	send '/compact'
/cost	send '/cost'
/help	send '/help'
/clear	send '/clear'
/diff	send '/diff'
/fast	send '/fast'
/vim	send '/vim'
/context	send '/context'
/export	send '/export'
/copy	send '/copy'
/rewind	send '/rewind'
/fork	send '/fork'
/permissions	send '/permissions'
/tasks	send '/tasks'
/status	send '/status'
/stats	send '/stats'
/review	send '/review'
/theme	send '/theme'
/sandbox	send '/sandbox'
Any /xxx command	send '/xxx'

These are NOT OpenClaw commands — forward them verbatim to CC. All CC slash commands work via passthrough, including ones not listed above.

Handling CC Approval Prompts

When CC encounters a tool it needs permission to run, it shows a TUI selection menu (arrow-key navigation, not text input). The approve action handles this:

CC shows:
  Do you want to proceed?
  ❯ 1. Yes
    2. Yes, allow from this project
    3. No

The user's reply should be interpreted:

• "y" / "是" / "好" / "1" / "同意" → approve 1
• "2" / "允许" / "一直允许" → approve 2
• "n" / "否" / "不" / "3" / "拒绝" → approve 3
• "取消" / "cancel" → approve esc

Long Tasks & Streaming

For tasks that take a long time (refactoring, writing large codebases):

1. Detect intent: if the user's message implies a large task (e.g. "重构整个项目", "帮我写一个完整的 XXX"), use --long flag (5-minute timeout)
2. If the output is empty after timeout, use peek to check CC's current state
3. If CC is still working, inform the user: CC 仍在处理中，稍后再查
4. Then use peek or history to get progress updates

Formatting — Seamless Mode

Goal: make the user feel like they're talking to Claude Code directly.

When CC session is active:

• Do NOT prefix every reply with 🤖 CC → — just relay CC's output directly
• Only add brief status markers for: · Session startup / shutdown · Approval prompts (show the options) · Errors / timeouts
• CC's code blocks, file paths, tool output → relay as-is, no reformatting
• Empty output → brief CC 处理中... then try peek after 3s
• Output >3000 chars → show last 2000 chars, note /cc history for full output
• Approval prompt → show options directly, minimal decoration

Error Handling

Situation	Action
send returns empty	Wait 3s, run peek, relay result
Session not found	Inform user, offer to start
Session crashed	Detect via status, offer restart
CC shows error	Relay error verbatim
Timeout on long task	Inform user, suggest peek or history

Additional Resources

• scripts/claude-code-bridge.sh — Full session management (start/send/approve/stop/restart/status/workdir/peek/history)
• references/usage.md — User-facing help text and example conversations