Claude Code Bridge

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/cc-bridge/scripts/cc-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?
       "启动cc"    → start
       "关闭cc"    → stop
       "重启cc"    → restart
       "cc状态"    → status
       "/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

Executing Actions

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

"$SCRIPT" "<ID>" start                    # 启动
"$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>" status                  # 状态
"$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'
/help	send '/help'
/cost	send '/cost'
/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 Replies

1. Prefix CC output with 🤖 **CC →**
2. Keep code blocks, file paths, and tool output intact
3. If output is empty: reply ⏳ CC 正在处理中... then try peek after 3s
4. If output >3000 chars: show the last 2000 chars, note earlier output available via /cc history
5. If CC is waiting for approval: clearly show the options to the user

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/cc-bridge.sh — Full session management (start/send/approve/stop/restart/status/peek/history)
• references/usage.md — User-facing help text and example conversations