@clawos-dev/clawd
Clawd daemon CLI：管理 Claude Code、Codex、pi 会话，通过 WebSocket 与 HTTP RPC 提供会话、persona、权限、历史和远程接入能力。
安装与启动
CLI 需要已修补的 Node.js：22.23.4+（22.x）、24.22.1+（24.x）或 26.12.1+（26.x）。Node 18/20 已停止维护，不再支持。仓库开发环境可在根目录运行 nvm install && nvm use。
npx @clawos-dev/clawd@latest
npx @clawos-dev/clawd@latest --port 28790
npx @clawos-dev/clawd@latest --data-dir /path/to/data
npx @clawos-dev/clawd@latest --tunnel
npx @clawos-dev/clawd@latest --web
也可全局安装后运行 clawd。默认监听 127.0.0.1:18790，数据目录为 ~/.clawd；参数与配置的当前定义见 config.ts。完整参数用 clawd --help 查看。
常用选项：--port、--data-dir、--config、--log-level、--tunnel、--clawos-api、--auth-token、--no-log-shipping。环境变量由 resolveConfig 解析，不根据旧示例猜测支持范围。
浏览器管理网页（--web）
clawd --web 启动（或复用已在运行的）本机 daemon，并在默认浏览器打开 daemon 内置的管理网页 /app/，无需安装桌面 App。
- 前台运行：CLI 自己启动的 daemon 随终端退出而停止（Ctrl-C）；复用已运行的 daemon 时，CLI 打开页面后立即退出，不影响它。
- 固定端口：未指定
--port且配置文件没有端口时，同一数据目录首次选 18790（被占用则选一个空闲端口）并记录在<data-dir>/web-port.json，之后不再变化——浏览器的存储按来源隔离，端口变了就等于换了一个页面。记录的端口被无关进程占用时直接报错，不会悄悄换端口。显式--port按原样使用，不写记录。 - 登录方式：CLI 通过已认证的
web:open取得一次性启动链接（随机 256 bit、60 秒、只能用一次、票据在 URL fragment 里），页面立即清除 fragment 并换取网页会话（7 天，绑定页面来源，服务端只存摘要，存放在<data-dir>/web-sessions.json，权限 0600）。会话 token 只放在该标签页的sessionStorage，关闭标签页后重新运行命令。长期 owner token 不会通过协议帧下发给页面（ready / info 里的httpToken换成该会话自己的 token）。注意：网页会话本身是 owner 等价的，同源脚本能做 owner 能做的事，所以预览内容必须保持沙箱隔离；Origin校验只防浏览器，本机其他进程可以伪造请求头，这与本机 loopback 信任边界一致。会话没有吊销入口，到期或删除web-sessions.json才失效；已建立的 WebSocket 连接不会在会话到期时被断开。启动链接会出现在浏览器启动进程的参数里（约 60 秒内有效）。 - 不兼容的旧 daemon：已有 daemon 版本过旧或不应答时，命令会给出明确提示并退出，不会替换别人启动的进程。
- 打开失败：找不到浏览器或启动器退出失败时明确报错；日志里只会出现不含票据的基础地址。
BROWSER可指定启动器可执行文件，启动器应在把链接交给浏览器后退出，以非零退出码报告失败。 - 首版边界：macOS + Chrome；不含后台服务安装、Windows 支持；
--tunnel下的公网来源不支持网页登录。
鉴权与远程接入
- WebSocket：无 tunnel 时 loopback 连接可豁免首帧鉴权；启用 tunnel 后 loopback 也要求鉴权。需要鉴权的客户端发送
{"type":"auth","token":"<token>"}并等待auth:ok后再发送业务帧。凭据决定 owner / guest 身份与权限，不由客户端自报身份。 - 浏览器来源：带
Origin头的 WebSocket 连接（即网页）即使来自 loopback 也必须鉴权，不能借用本机免认证；无Origin的 native / CLI 客户端保持原行为。旧桌面端的file://（Origin: null）连接持有效 owner token 时照常可用。本地用 Vite 开发（pnpm dev）时，需用环境变量CLAWD_WEB_DEV_ORIGINS=http://localhost:5173（逗号分隔，可多个）启动 daemon，把开发页面来源显式列为豁免。 - 文件预览隔离：
/files/*与/session/*/files返回的 HTML / SVG 一律带Content-Security-Policy: sandbox allow-scripts——脚本可以运行以便预览，但页面处于不透明来源，读不到管理页的存储，也不能操作 opener / parent、弹窗或导航顶层。前端 Blob 预览仅允许被动图片和视频 MIME；SVG 不走 Blob 内嵌预览，伪装成媒体文件名的 SVG/HTML/XML 响应也会被拒绝，避免转换为同源 Blob 时丢失沙箱保护。 - HTTP RPC：无论是否启用 tunnel 都使用已解析的 Bearer token。WebSocket 的本机豁免不适用于 HTTP。
--tunnel注册公网隧道并启动 frpc，使手机和授权的远端客户端能连接本机 daemon。连接串包含凭据，只交给授权客户端，不贴入诊断报告。
本地 owner token、中心登录票 loginPass、云 gateway API key 各自有不同用途；当前边界见 identity 和 peer-mesh。
查询状态与排障
persona / 会话 / 联系人 / 任务 / tunnel 的实际状态先通过 clawd-rpc 的 list + call 查询。会话列表走 session:list；历史读取用 history:read 并加 slim:true。不要按旧目录示例拼路径，也不直接读取 auth.json 或含 connectToken 的联系人记录。
默认日志在 ~/.clawd/log/，daemon 主日志为 clawd.log。远端和云 persona 状态不能由本机文件判断；按 日志排障手册 查对应时间窗与 owner。
开发入口
- 工作规范：CLAUDE.md与workspace 规范。
- wire 字段与 schema：protocol/src/；说明见 wire-protocol。
- 模块边界和当前术语：glossary。
- 运行时持久化布局：disk-layout，它是实现说明，不是状态查询接口。
License
MIT