| name | claude-code-remote |
| description | Launch a Claude Code remote control session via claude-code-remote-control. Use when the user wants to start a remote Claude Code session in a specific project directory, control Claude Code from a browser/mobile, or mentions claude-code-remote-control. |
Claude Code Remote Control
Start a browser-accessible Claude Code session in a specified project directory.
Workflow
- Determine the project directory — User specifies
--cwd path, or default to workspace
- Start the server in background using
exec
- Parse the output to get URL and token
- Generate a QR code with the auto-connect URL
- Construct auto-connect URL（带 token + expires 参数）
- Report the URL + QR code to the user
Start a Session
npx claude-code-remote-control serve --cwd <project-dir> [options]
Options:
--cwd <dir> — Claude Code working directory (required)-p, --port <port> — Port (default: 3456)-t, --token <token> — Auth token (auto-generated if omitted)--model <model> — Claude model name--permission-mode <mode> — default | accept-edits | bypass-permissions--tunnel — Auto-start cloudflared tunnel for public access (requires cloudflared)--token-expires <minutes> — Token 有效期（分钟），默认使用 10
Step-by-Step Execution
1. Start the server
使用 exec 的 background 模式启动：
npx claude-code-remote-control serve --cwd /path/to/project --tunnel --token-expires 10
默认参数：
--token-expires 10（token 有效期 10 分钟）--tunnel（开启公网隧道，除非用户不需要公网访问）
如果端口被占用，先 kill 再启动：
lsof -ti:<port> | xargs kill -9 2>/dev/null; sleep 1; npx ...
2. Wait and parse output
Poll the process output to提取 URL（本地地址 + tunnel 公网地址）和 token。服务端输出的 QR code 也是基于自动连接 URL 生成的，可直接使用。
3. Generate QR code
服务端启动时会自动输出 QR code。如果需要自定义（比如带 token+expires 的 URL），可以用 qrencode：
qrencode -o /tmp/openclaw/claude-remote-qr.png "<base-url>?token=<token>&expires=<unix-timestamp-ms>"
如果 qrencode 不可用：brew install qrencode
然后通过 image 工具展示 QR code 给用户。
飞书场景：如果当前在飞书 channel 中，需要额外将 QR code 图片上传到飞书并发送：
- 用 qrencode 生成图片：
qrencode -o /tmp/openclaw/claude-remote-qr.png "<auto-connect-url>"
- 使用飞书 IM 上传图片 API（以机器人身份）上传图片获取
image_key
- 发送图片消息给用户预览
上传成功后拿到 image_key，然后发送 image 类型消息给用户。
4. Construct auto-connect URL
必须将 token 和 expires 参数拼接到 URL 上，否则用户需要手动输入 token。
计算 expires 时间戳（当前 UTC 时间 + 10 分钟，单位为毫秒）：
date -u -v+10M +%s%3N
最终 URL 格式：
<base-url>?token=<token>&expires=<unix-timestamp-ms>
例如（毫秒级时间戳，13位）：
https://xxx.trycloudflare.com?token=mniyk4w-xxx&expires=1775208720000
页面加载时会自动解析 URL 参数，验证 token 后直接建立 WebSocket 连接，跳过手动输入。
4. Report to user
必须使用以下固定格式回复用户：
✅ Claude Code 已启动
📂 工作目录：/path/to/project
🔗 访问地址：<完整 trycloudflare.com URL?token=xxx&expires=xxx>
⏳ 链接 10 分钟内有效
规则：
- 必须包含工作目录完整路径
- 必须包含带 token+expires 参数的完整 URL
- 必须提示有效期
- 不要省略任何信息，不要只发 localhost:port
5. Stop the server
直接 kill 端口即可，无需额外清理：
lsof -ti:<port> | xargs kill -9
Important Notes
- URL 必须带参数：报告给用户的 URL 必须包含
?token=<token>&expires=<unix-timestamp-ms>（毫秒级），这样打开页面会自动连接，无需手动输入 token
- 默认权限模式：不要使用
--permission-mode bypass-permissions，除非用户明确要求。默认不传该参数即可
- 端口冲突处理：如果端口被占用，默认先 kill 掉占用该端口的旧进程再启动（
lsof -ti:<port> | xargs kill -9），除非用户明确要求保留旧实例并开启新的（此时才换端口）
- Token 过期：token 有效期 10 分钟（
--token-expires 10），过期后需 kill 旧进程重新启动
- Server runs as a background process; use
process tool to manage it
