@clawos-dev/clawd

独立 clawd daemon —— Claude Code（以及未来的 Codex 等）会话服务，对外暴露 WebSocket 协议。

安装与启动

推荐用 npx，每次自动拉最新版（无需全局安装）：

npx @clawos-dev/clawd@latest                          # 默认 ws://127.0.0.1:18790
npx @clawos-dev/clawd@latest --port 28790             # 自定义端口
npx @clawos-dev/clawd@latest --data-dir /path/to/data # 覆盖默认 ~/.clawd
npx @clawos-dev/clawd@latest --tunnel                 # 远程：起 frp tunnel + first-message token 鉴权

也可以 npm i -g @clawos-dev/clawd 后直接 clawd …。

启动成功 stdout 会打印 Ready: ws://127.0.0.1:18790，运行时元数据（{url, pid, authToken?, tunnelUrl?, ...}）写入 ~/.clawd/state.json（0600 权限）。

本机模式无鉴权：监听 127.0.0.1，所有连接直接放行；--tunnel 模式强制开启 first-message token 鉴权。

CLI 参数

| Flag | 默认 | 说明 | |---|---|---| | --port <n> | 18790 | WebSocket 监听端口 | | --data-dir <path> | ~/.clawd | 数据目录 | | --config <path> | <data-dir>/config.json | 配置文件（存在则加载） | | --log-level <level> | info | debug / info / warn / error | | --tunnel | false | 启用 frp tunnel 把本地端口暴露到公网 | | --clawos-api <url> | https://api.clawos.chat | tunnel register 接口 base url | | --auth-token <s> | 自动生成 | 指定 daemon auth token；缺省时 tunnel 模式从 ~/.clawd/auth.json 复用，不存在则生成 32 字节 base64url | | --help / -h | — | 显示帮助 | | --version / -v | — | 显示版本 |

环境变量（高级）

| Var | 说明 | |---|---| | CLAWD_FRPC_BIN | 自带 frpc 二进制路径（缺省时按需下载到 ~/.clawd/bin/frpc） | | CLAWD_NO_TUNNEL_PERSIST | =1 启动时不复用 ~/.clawd/tunnel.json（dev only；NODE_ENV=development 自动开启） | | CLAWD_TUNNEL | =1 等价于 --tunnel | | CLAWOS_API | 等价于 --clawos-api | | CLAWD_AUTH_TOKEN | 等价于 --auth-token |

Tunnel 模式

零参数即可启用：

clawd --tunnel

启动后 stdout 会输出一段 banner，包含 tunnel URL 与一键连接串：

══════════════════════════════════════════════════════
  Tunnel:      wss://abcd1234.tunnel.clawos.chat
  Connect:     wss://abcd1234.tunnel.clawos.chat#token=kF3p...
  Frpc config: ~/.clawd/frpc.toml
  Frpc log:    ~/.clawd/frpc.log
══════════════════════════════════════════════════════

把 Connect: 整行复制到客户端的"远程连接"输入框即可，客户端会从 fragment 拆出 token。同样的内容也会落盘到 ~/.clawd/connect.txt（0600）方便事后查阅。

要换 register base url：--clawos-api https://example.com。

启用后 daemon 会：

1. 调 POST <clawos-api>/api/tunnel/register 拿 frps 凭证
2. 缓存到 ~/.clawd/tunnel.json（0600，TTL 7 天，下次启动复用）
3. 按 OS/arch 下载 frpc 到 ~/.clawd/bin/frpc（仅首次）
4. 写 ~/.clawd/frpc.toml 并 spawn frpc 子进程
5. 把 tunnelUrl 写进 ~/.clawd/state.json

退出时 SIGTERM frpc 子进程，5 秒后 SIGKILL。

Auth: first-message handshake

启用 tunnel 时，daemon 强制要求 first-message auth：

• 客户端连上后 5 秒内必须发送 {"type":"auth","token":"<token>"}
• 通过 → daemon 回 {"type":"auth:ok"}
• 失败 / 超时 / 越权 → close code 1008

token 来源（任选其一）：

• 启动 banner 里 Connect: 整行（带 #token=），客户端一次粘贴即可
• 单独从 Auth Token: 行复制
• ~/.clawd/state.json 的 authToken 字段（0600，仅本机用户可读）

非 tunnel 模式下，127.0.0.1 / ::1 来源连接默认豁免 auth；--tunnel 模式所有连接都要 auth。

目录结构

~/.clawd/
├── config.json                # 可选配置文件
├── state.json                 # 运行时发现文件（启动写，退出删）
├── auth.json                  # tunnel auth token 持久化
├── tunnel.json                # frps 凭证缓存
├── connect.txt                # tunnel 连接串
├── frpc.toml / frpc.log       # frpc 子进程配置 / 日志
├── clawd.log                  # daemon 运行日志
└── sessions/default/*.json    # 会话持久化

License

MIT