# @clawos-dev/clawd 中文文档 规范地址：https://npmcn.com/package/%40clawos-dev/clawd/ 版本：0\.2\.763 npm 元数据更新时间：2026-11-11T05:50:13.975Z 中文译文更新时间：2026-11-11T05:08:39.312Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40clawos-dev/clawd 原文对照：https://npmcn.com/package/%40clawos-dev/clawd/?lang=original 项目主页：https://clawos.chat/ ## 关键信息（来自 npm 元数据） - 包体积（解压后）：20.1 MB，127 个文件 - 模块格式：ES Module - TypeScript 类型：未声明 - Node.js 要求：^22\.23\.4 \|\| ^24\.22\.1 \|\| ^26\.12\.1 - 运行依赖：8 个 - 首次发布：2026-04-27T05:59:57.640Z - 最新版本发布：2026-11-11T05:50:13.758Z - 近 30 天下载量：31701（2026-10-10 至 2026-11-08，npm 官方下载统计） - 已发布版本数：1156（近 12 个月 1156 个） ## 中文简介 独立的爪子守护进程 — Claude Code (和未来 Codex) 会话服务器通过 WebSocket ## 安装 ```sh npm install @clawos-dev/clawd ``` 也可以使用：`pnpm add @clawos-dev/clawd`、`yarn add @clawos-dev/clawd`、`bun add @clawos-dev/clawd` ## README # @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`。 ```bash 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](https://npmcn.com/package/%40clawos-dev/clawd/src/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（被占用则选一个空闲端口）并记录在 `/web-port.json`，之后不再变化——浏览器的存储按来源隔离，端口变了就等于换了一个页面。记录的端口被无关进程占用时直接报错，不会悄悄换端口。显式 `--port` 按原样使用，不写记录。 - **登录方式**：CLI 通过已认证的 `web:open` 取得一次性启动链接（随机 256 bit、60 秒、只能用一次、票据在 URL fragment 里），页面立即清除 fragment 并换取网页会话（7 天，绑定页面来源，服务端只存摘要，存放在 `/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":""}` 并等待 `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](https://npmcn.com/package/%40clawos-dev/doc/glossary/identity.md) 和 [peer-mesh](https://npmcn.com/package/%40clawos-dev/doc/glossary/peer-mesh.md)。 ## 查询状态与排障 persona / 会话 / 联系人 / 任务 / tunnel 的实际状态先通过 `clawd-rpc` 的 `list` + `call` 查询。会话列表走 `session:list`；历史读取用 `history:read` 并加 `slim:true`。不要按旧目录示例拼路径，也不直接读取 `auth.json` 或含 connectToken 的联系人记录。 默认日志在 `~/.clawd/log/`，daemon 主日志为 `clawd.log`。远端和云 persona 状态不能由本机文件判断；按 [日志排障手册](https://npmcn.com/package/%40clawos-dev/doc/debug-with-logs.md) 查对应时间窗与 owner。 ## 开发入口 - 工作规范：[CLAUDE.md](https://npmcn.com/package/%40clawos-dev/clawd/CLAUDE.md)与[workspace 规范](https://npmcn.com/package/%40clawos-dev/CLAUDE.md)。 - wire 字段与 schema：[protocol/src/](https://npmcn.com/package/%40clawos-dev/protocol/src/)；说明见 [wire-protocol](https://npmcn.com/package/%40clawos-dev/doc/glossary/wire-protocol.md)。 - 模块边界和当前术语：[glossary](https://npmcn.com/package/%40clawos-dev/doc/glossary/README.md)。 - 运行时持久化布局：[disk-layout](https://npmcn.com/package/%40clawos-dev/doc/glossary/disk-layout.md)，它是实现说明，不是状态查询接口。 ## License MIT ## 常见问题 ### @clawos-dev/clawd 是什么？ 独立的爪子守护进程 — Claude Code \(和未来 Codex\) 会话服务器通过 WebSocket ### 如何安装 @clawos-dev/clawd？ 在项目目录运行 npm install @clawos-dev/clawd，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 clawd，可以用 npx clawd 直接运行。 ### @clawos-dev/clawd 支持 TypeScript 吗？ 该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/clawos-dev\_\_clawd 是否存在。 ### @clawos-dev/clawd 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @clawos-dev/clawd 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js ^22\.23\.4 \|\| ^24\.22\.1 \|\| ^26\.12\.1。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @clawos-dev/clawd 可以商用吗？ @clawos-dev/clawd 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @clawos-dev/clawd 的下载量有多少？ 根据 npm 官方下载统计，@clawos-dev/clawd 在 2026/10/10 – 2026/11/08 这 30 天内被下载 31,701 次，日均约 1,057 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @clawos-dev/clawd 还在维护吗？ 最新版本 0\.2\.763 发布于 2026/11/11（今天）；至今共发布 1156 个版本，其中过去 12 个月发布了 1156 个；首次发布于 2026/04/27。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。