Claude Code Remote Executor

Claude Code 远程执行 Skill — 通过三通道（FastAPI/Redis/Screen）向远程机器上的 Claude Code 派发指令，支持重试机制。触发：博士让我"派发给 Claude Code"、"远程执行"、"让XX机器执行Claude Code"、remote cc。

cc-remote

通过三通道向远程机器上的 Claude Code 派发指令，支持重试机制。

部署架构

我 (NAS/OpenClaw)
    │
    ├─→ FastAPI:18900 ──→ Worker 监听 Redis ──→ Claude Code 执行
    │       ↑
    │    HTTP POST
    │
    └─→ Redis LPUSH ──→ Worker BLPOP ──→ Claude Code 执行
            ↑
        直接写队列

远程机器需要运行：

• FastAPI 服务（端口 18900）
• Redis Worker（监听 Redis 队列）
• Redis（可连的队列服务）

首次部署（远程机器）

在远程机器上运行：

# 安装依赖
pip3 install redis uvicorn fastapi

# 启动 Worker（后台常驻）
nohup python3 cc_worker.py > worker.log 2>&1 &

# 启动 API
nohup python3 cc_api.py > api.log 2>&1 &

三通道（按优先级）

通道	原理	稳定性
fastapi	HTTP POST 到远程 API，Worker 执行	⭐⭐⭐ 最稳定
redis	直接 LPUSH 到 Redis 队列	⭐⭐
screen	SSH Screen 后台执行	⭐ fallback

重试机制

• 每个通道最多 3 次重试
• 失败后等待 5~7 秒随机
• 三通道全失败 → 返回错误

配置修改

首次使用前，编辑 scripts/exec.py 顶部配置：

M1_HOST = "远程机器IP"        # 如 "192.168.0.128"
M1_API_PORT = 18900           # FastAPI 端口
REDIS_HOST = "Redis服务器IP"  # 如 "192.168.0.107"
REDIS_PORT = 11980            # Redis 端口

使用方式

python3 scripts/exec.py "你的指令"

参数

参数	说明
prompt	要执行的指令（必须）
--task-id	指定任务ID
--timeout	超时秒数（默认300）
--channel	强制指定通道（fastapi/redis/screen）

示例

# 基本用法（自动选择通道）
python3 scripts/exec.py "say hello"

# 强制用 fastapi
python3 scripts/exec.py "say hello" --channel fastapi

# 指定任务ID，方便查结果
python3 scripts/exec.py "修改 index.html" --task-id fix001

远程机器进程管理

# 查看进程
ssh 远程机器 "ps aux | grep cc_"

# 重启 Worker
ssh 远程机器 "pkill -f cc_worker; nohup python3 ~/cc_worker.py > ~/worker.log 2>&1 &"

# 重启 API
ssh 远程机器 "pkill -f cc_api; nohup python3 ~/cc_api.py > ~/api.log 2>&1 &"

故障排查

任务提交成功但没结果：

1. 查远程机器 Worker 日志：ssh 远程机器 "tail worker.log"
2. 查 API 状态：curl http://远程机器IP:18900/health
3. 查 Redis 队列：redis-cli -h Redis服务器 -p 端口 LLEN claude_tasks

FastAPI 连不上：

• 检查远程机器 API 是否在跑
• 重启 API

Worker 不处理队列：

• 检查 worker 是否在跑
• 重启 worker

指令构造技巧

发给 Claude Code 的指令要清晰：

• 说明要改哪个文件
• 说明改什么
• 说明期望效果
• 复杂任务加"逐步思考"

好例子：

修改 /path/to/project/web/index.html：

1. 找到 body 样式部分
2. 添加背景色：background: #f5f5f5
3. 确保在移动端也生效（响应式）

注意：先备份原文件。

文件说明

文件	功能
exec.py	三通道执行器（核心）
deploy_m1.py	远程机器一键部署脚本
deploy_ssh.py	SSH 强化配置（连接池复用）