Claude Code 远程执行 Skill — 通过三通道(FastAPI/Redis/Screen)向远程机器上的 Claude Code 派发指令,支持重试机制。触发:博士让我"派发给 Claude Code"、"远程执行"、"让XX机器执行Claude Code"、remote cc。
---
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**(可连的队列服务)
## 首次部署(远程机器)
在远程机器上运行:
```bash
# 安装依赖
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` 顶部配置:
```python
M1_HOST = "远程机器IP" # 如 "192.168.0.128"
M1_API_PORT = 18900 # FastAPI 端口
REDIS_HOST = "Redis服务器IP" # 如 "192.168.0.107"
REDIS_PORT = 11980 # Redis 端口
```
## 使用方式
```bash
python3 scripts/exec.py "你的指令"
```
### 参数
| 参数 | 说明 |
|------|------|
| `prompt` | 要执行的指令(必须) |
| `--task-id` | 指定任务ID |
| `--timeout` | 超时秒数(默认300) |
| `--channel` | 强制指定通道(fastapi/redis/screen) |
### 示例
```bash
# 基本用法(自动选择通道)
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
```
## 远程机器进程管理
```bash
# 查看进程
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 强化配置(连接池复用) |
don't have the plugin yet? install it then click "run inline in claude" again.