@clawos-dev/clawd 0.2.626 → 0.2.628

package/README.md

@@ -1,109 +1,40 @@
 # @clawos-dev/clawd
 
-独立 clawd daemon —— Claude Code（以及未来的 Codex 等）会话服务，对外暴露 WebSocket 协议。
+Clawd daemon CLI：管理 Claude Code、Codex、pi 会话，通过 WebSocket 与 HTTP RPC 提供会话、persona、权限、历史和远程接入能力。
 
 ## 安装与启动
 
-推荐用 `npx`，每次自动拉最新版（无需全局安装）：
-
 ```bash
-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 鉴权
+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
 ```
 
-也可以 `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 鉴权。
+也可全局安装后运行 `clawd`。默认监听 `127.0.0.1:18790`，数据目录为 `~/.clawd`；参数与配置的当前定义见 [config.ts](./src/config.ts)。完整参数用 `clawd --help` 查看。
 
-## CLI 参数
+常用选项：`--port`、`--data-dir`、`--config`、`--log-level`、`--tunnel`、`--clawos-api`、`--auth-token`、`--no-log-shipping`。环境变量由 `resolveConfig` 解析，不根据旧示例猜测支持范围。
 
-| 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` | — | 显示版本 |
+## 鉴权与远程接入
 
-### 环境变量（高级）
+- **WebSocket**：无 tunnel 时 loopback 连接可豁免首帧鉴权；启用 tunnel 后 loopback 也要求鉴权。需要鉴权的客户端发送 `{"type":"auth","token":"<token>"}` 并等待 `auth:ok` 后再发送业务帧。凭据决定 owner / guest 身份与权限，不由客户端自报身份。
+- **HTTP RPC**：无论是否启用 tunnel 都使用已解析的 Bearer token。WebSocket 的本机豁免不适用于 HTTP。
+- `--tunnel` 注册公网隧道并启动 frpc，使手机和授权的远端客户端能连接本机 daemon。连接串包含凭据，只交给授权客户端，不贴入诊断报告。
 
-| 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` |
+本地 owner token、中心登录票 loginPass、云 gateway API key 各自有不同用途；当前边界见 [identity](../doc/glossary/identity.md) 和 [peer-mesh](../doc/glossary/peer-mesh.md)。
 
-## Tunnel 模式
-
-零参数即可启用：
-
-```bash
-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）方便事后查阅。
+persona / 会话 / 联系人 / 任务 / tunnel 的实际状态先通过 `clawd-rpc` 的 `list` + `call` 查询。会话列表走 `session:list`；历史读取用 `history:read` 并加 `slim:true`。不要按旧目录示例拼路径，也不直接读取 `auth.json` 或含 connectToken 的联系人记录。
 
-要换 register base url：`--clawos-api https://example.com`。
+默认日志在 `~/.clawd/log/`，daemon 主日志为 `clawd.log`。远端和云 persona 状态不能由本机文件判断；按 [日志排障手册](../doc/debug-with-logs.md) 查对应时间窗与 owner。
 
-启用后 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    # 会话持久化
-```
+- 工作规范：[CLAUDE.md](./CLAUDE.md)与[workspace 规范](../CLAUDE.md)。
+- wire 字段与 schema：[protocol/src/](../protocol/src/)；说明见 [wire-protocol](../doc/glossary/wire-protocol.md)。
+- 模块边界和当前术语：[glossary](../doc/glossary/README.md)。
+- 运行时持久化布局：[disk-layout](../doc/glossary/disk-layout.md)，它是实现说明，不是状态查询接口。
 
 ## License
 

package/dist/cli.cjs

@@ -73600,7 +73600,7 @@ function computeMethodAccess(args) {
 }
 
 // src/version.ts
-var version = "0.2.626".length > 0 ? "0.2.626" : "dev";
+var version = "0.2.628".length > 0 ? "0.2.628" : "dev";
 
 // src/cli-probe/probe.ts
 var fs84 = __toESM(require("fs"), 1);