@clawos-dev/clawd 0.2.626 → 0.2.627

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.627".length > 0 ? "0.2.627" : "dev";
 
 // src/cli-probe/probe.ts
 var fs84 = __toESM(require("fs"), 1);

package/dist/persona-defaults/persona-clawd-butler/.claude/skills/clawd-introspection/SKILL.md

@@ -11,32 +11,15 @@ description: 老板问本机 clawd 状态时触发——装了哪些 persona/ext
 
 **第一步先走 RPC**（clawd-rpc MCP 的 list / call）——daemon 在跑时它是状态的真源，目录布局只是实现细节。用 list 拉方法表（每条带中文说明），对着老板的问题挑方法调；方法表就是能力清单，别凭印象说 clawd 没有某能力。
 
-**RPC 查不到答案、或 daemon 没在跑，再翻文件。** 先 fetch 一次 `${CLAWOS_API}/api/docs/introspection/file-map.md`——它讲 `~/.clawd/` 下每个文件/目录是干啥的，是文件路线的地图。
+**文档只解释结构，不代表当前状态。** 需要了解字段含义时 fetch `${CLAWOS_API}/api/docs/introspection/file-map.md` 或 `state-schemas.md`；故障表征参考 `common-issues.md`。
 
-然后按具体子问题挑：
+**不直接读凭证或扫目录列状态。** `auth.json`、带凭证的 tunnel / owner identity 文件和含 connectToken 的 `contacts.json` 不读、不贴、不落盘；不调会返回 connectToken 的 `contact:list`。联系人授权通过界面或方法表里不返回凭证的接口查看。
 
-| 老板问的 | fetch |
-|---|---|
-| 具体 state/auth/tunnel/dispatch json 里字段啥意思 | `${CLAWOS_API}/api/docs/introspection/state-schemas.md` |
-| 典型故障表征怎么排（比如 tunnel 挂了、dispatch 卡住、session 报错） | `${CLAWOS_API}/api/docs/introspection/common-issues.md` |
-
-**文件兜底清单（Read / Bash）** —— 仅在 RPC 答不了时用：
-
-- `~/.clawd/state.json` daemon 运行时状态（pid / url / tunnelUrl）
-- `~/.clawd/tunnel.json` 远程接入配置
-- `~/.clawd/dispatch.json` dispatch 台账（正在跑 / 已完成的任务）
-- `~/.clawd/contacts.json` 联系人 + 授权（T-35 后授权数据全在这一份，legacy `capabilities.json` / `received-capabilities.json` 已 retire）
-- `~/.clawd/personas/` 装了哪些 persona
-- `~/.clawd/extensions-published.json` / `~/.clawd/extensions/` 装了哪些 extension
-- `~/.clawd/*.log` 各类 log（`clawd.log` 是 daemon 主 log）
-
-读文件时凭证不外显：`auth.json`（owner token）整份别读，`contacts.json` 里的 `connectToken` 等 token / secret 字段不贴进回答、不落盘。
-
-排障时：先走 RPC 看 daemon 侧状态；daemon 没响应再按 file-map 定位文件 Read，最后按 common-issues 里的表征匹配可能原因。
+RPC 不可用时说明无法确认当前状态。诊断可按用户的时间窗读取 `~/.clawd/log/clawd.log`、`frpc.log` 等日志，禁止把 persona 目录、旧 JSON 或远端不在本机的文件当作实时清单。读会话走 `history:read`，一定加 `slim:true`。
 
 ## fetch 失败了
 
-fetch 不到文档就照本机文件+ 现有认知答。**如果本机文件也答不了、又需要文档知识，直接告诉老板"我需要那份自省文档但拉不到，稍后再问一次或让 David 看一眼"**。别瞎猜字段含义。
+fetch 不到文档时仍先用 RPC 方法表与返回结果回答；需要的结构知识无法核实时，明确说明缺少哪份文档。RPC 也不可用就说明无法确认当前状态，不以目录或旧文件补猜。
 
 ## 回答风格
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawos-dev/clawd",
-  "version": "0.2.626",
+  "version": "0.2.627",
   "description": "Standalone clawd daemon — Claude Code (and future Codex) session server over WebSocket",
   "type": "module",
   "license": "MIT",