Claude Code Remote Executor

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

Security Scan

The skill largely implements what it claims (remote dispatch to Claude Code via FastAPI/Redis/SSH), but there are several mismatches and risky choices (notably the 'screen' channel executing the raw prompt as a shell command, hard-coded user paths, and permissive worker invocation flags) that warrant caution before installing or enabling autonomous use.

Purpose & Capability

The name/description (dispatch prompts to a remote Claude Code) matches the code: FastAPI and Redis worker implementations submit prompts to a local 'claude' binary. However the Screen channel implementation executes the user-supplied prompt directly in a remote shell (screen -> /bin/zsh -c "prompt") instead of invoking the Claude CLI; that is a functional divergence from the stated purpose and increases risk.

Instruction Scope

SKILL.md and scripts instruct the agent/user to edit config with remote IPs and to use SSH/scp to upload and restart remote services. The worker runs a local claude binary with '--permission-mode bypassPermissions', and the Screen channel runs arbitrary shell commands derived from the prompt — both are broad actions. The SKILL.md also directs reading remote logs and running shell commands (via ssh) for process management, which is expected for remote orchestration but expands scope to full remote shell control.

Install Mechanism

There is no install spec that downloads arbitrary artifacts; the package is instruction + scripts. That lowers install risk. The deploy scripts use scp/ssh to write files on the remote host, which is expected for a remote-deploy tool.

Credentials

No environment variables or external credentials are declared for the skill bundle, which is consistent. However the scripts assume SSH key-based access and hard-coded user paths (/Users/m1-meng, ~/.npm-global, workspace paths) and a reachable Redis instance; these hard-coded paths suggest the package was tailored to a specific environment and will require editing. The worker passes the process' os.environ when invoking the claude binary (i.e., it inherits environment variables), which could unintentionally expose environment values to the remote process.

Persistence & Privilege

always:false and no special platform-level persistence flags are present. The skill's deploy scripts do write and restart services on the remote machine (creating persistent worker/API there), but they do not modify other skills or system-wide agent settings on the local platform.

What to consider before installing

This skill will cause code to run on a remote machine you point it at (via SSH, FastAPI, or Redis). Before installing or enabling autonomous use: 1) Review and edit all hard-coded values (REMOTE_HOST, SSH user, CLI paths) so they match your environment. 2) Understand the Screen channel: it runs the provided prompt directly in a remote shell (zsh -c), so any prompt can become an arbitrary shell command — this is the primary red flag. If you only want to send prompts to a claude CLI, remove/modify the Screen channel so it calls the claude binary rather than running raw input. 3) The worker runs the claude binary with '--permission-mode bypassPermissions' which can increase what the remote process can do; ensure you trust the remote host and the claude binary. 4) Ensure Redis and the FastAPI endpoint are protected (network ACLs, auth) to avoid unauthorized task submission. 5) Because the agent can invoke skills autonomously by default, avoid granting this skill autonomous access unless you trust the agent's behavior — otherwise require manual confirmation. 6) Run the deploy scripts in a controlled/test environment first and inspect the generated cc_worker.py / cc_api.py files on the remote host before starting them.

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 强化配置（连接池复用）