Claude Code Remote Executor

---

name: cc-remote description: 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 强化配置（连接池复用） |