@clawos-dev/clawd 0.2.2 → 0.2.3-beta.4.865defc

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +51 -87
  2. package/package.json +2 -10
package/README.md CHANGED
@@ -1,8 +1,8 @@
1
1
  # @clawos-dev/clawd
2
2
 
3
- 独立 clawd daemon——Claude Code（未来包含 Codex 等）会话服务，WebSocket 协议见 `../doc/clawd-protocol.md`。
3
+ 独立 clawd daemon —— Claude Code（以及未来的 Codex 等）会话服务，对外暴露 WebSocket 协议。
4
4
 
5
- ## 启动
5
+ ## 安装与启动
6
6
 
7
7
  推荐用 `npx`，每次自动拉最新版（无需全局安装）：
8
8
 
@@ -15,42 +15,56 @@ npx @clawos-dev/clawd@latest --tunnel # 远程：起 frp tunnel
15
15
 
16
16
  也可以 `npm i -g @clawos-dev/clawd` 后直接 `clawd …`。
17
17
 
18
- 启动成功后 stdout 会打印 `Ready: ws://127.0.0.1:18790`，完整 `{url, pid, ...}` 在 `~/.clawd/state.json`（0600 权限）。
18
+ 启动成功 stdout 会打印 `Ready: ws://127.0.0.1:18790`，运行时元数据（`{url, pid, authToken?, tunnelUrl?, ...}`）写入 `~/.clawd/state.json`（0600 权限）。
19
19
 
20
- > **当前阶段无鉴权**：本机 ws 监听 `127.0.0.1`，所有连接直接放行；未来公开远端 transport 时会再引入鉴权。
20
+ > **本机模式无鉴权**：监听 `127.0.0.1`，所有连接直接放行；`--tunnel` 模式强制开启 first-message token 鉴权。
21
21
 
22
22
  ## CLI 参数
23
23
 
24
- - `--port <n>` 监听端口，默认 18790
25
- - `--data-dir <path>` 数据目录，默认 `~/.clawd`
26
- - `--config <path>` 配置文件，默认 `<data-dir>/config.json`（若存在）
27
- - `--log-level <level>` `debug` / `info` / `warn` / `error`（默认 `info`）
28
- - `--server-url <url>` 反连远端中继（v2，暂未实装）
29
- - `--tunnel` 启用 frp tunnel 把本地端口暴露到公网（搭配 `--clawos-api`）
30
- - `--clawos-api <url>` `/api/tunnel/register` 接口的 base url
31
- - `--auth-token <s>` 指定 daemon auth token；缺省时 tunnel 模式自动生成 32 字节 base64url
32
- - `--no-auth` 关掉 first-message auth（仅开发用，stderr 警告）
33
- - `--no-tunnel-persist` 启动时不复用 `~/.clawd/tunnel.json`，强制重新 register
34
- - `--frpc-binary <path>` 指定本地 frpc 二进制；缺省时按需下载到 `~/.clawd/bin/frpc`
35
- - `--open` 启动后自动用系统默认浏览器打开 ext-clawd UI（需配 `--web-url`）
36
- - `--web-url <url>` ext-clawd setup 页面完整 URL；由 setup 页面生成的命令自动带
37
- - `--help` / `-h`、`--version` / `-v`
24
+ | Flag | 默认 | 说明 |
25
+ |---|---|---|
26
+ | `--port <n>` | `18790` | WebSocket 监听端口 |
27
+ | `--data-dir <path>` | `~/.clawd` | 数据目录 |
28
+ | `--config <path>` | `<data-dir>/config.json` | 配置文件（存在则加载） |
29
+ | `--log-level <level>` | `info` | `debug` / `info` / `warn` / `error` |
30
+ | `--tunnel` | `false` | 启用 frp tunnel 把本地端口暴露到公网 |
31
+ | `--clawos-api <url>` | `https://api.clawos.chat` | tunnel register 接口 base url |
32
+ | `--auth-token <s>` | 自动生成 | 指定 daemon auth token；缺省时 tunnel 模式从 `~/.clawd/auth.json` 复用，不存在则生成 32 字节 base64url |
33
+ | `--help` / `-h` | — | 显示帮助 |
34
+ | `--version` / `-v` | — | 显示版本 |
35
+
36
+ ### 环境变量（高级）
37
+
38
+ | Var | 说明 |
39
+ |---|---|
40
+ | `CLAWD_FRPC_BIN` | 自带 frpc 二进制路径（缺省时按需下载到 `~/.clawd/bin/frpc`） |
41
+ | `CLAWD_NO_TUNNEL_PERSIST` | `=1` 启动时不复用 `~/.clawd/tunnel.json`（dev only；`NODE_ENV=development` 自动开启） |
42
+ | `CLAWD_TUNNEL` | `=1` 等价于 `--tunnel` |
43
+ | `CLAWOS_API` | 等价于 `--clawos-api` |
44
+ | `CLAWD_AUTH_TOKEN` | 等价于 `--auth-token` |
38
45
 
39
46
  ## Tunnel 模式
40
47
 
41
- 零参数即可（默认 base url 是 `https://api.clawos.chat`）：
48
+ 零参数即可启用：
42
49
 
43
50
  ```bash
44
51
  clawd --tunnel
45
- # Ready: ws://127.0.0.1:18790
46
- # Auth Token: kF3p...43chars
47
- # Tunnel: wss://abcd1234.tunnel.clawos.chat
48
- # Connect: wss://abcd1234.tunnel.clawos.chat#token=kF3p...43chars
49
52
  ```
50
53
 
51
- 把 `Connect:` 整行复制到 ext-clawd UI 的"远程"模式输入框即可，UI 会自动从 fragment 拆出 token。
54
+ 启动后 stdout 会输出一段 banner，包含 tunnel URL 与一键连接串：
52
55
 
53
- 要换 base url：`--clawos-api https://example.com`
56
+ ```
57
+ ══════════════════════════════════════════════════════
58
+ Tunnel: wss://abcd1234.tunnel.clawos.chat
59
+ Connect: wss://abcd1234.tunnel.clawos.chat#token=kF3p...
60
+ Frpc config: ~/.clawd/frpc.toml
61
+ Frpc log: ~/.clawd/frpc.log
62
+ ══════════════════════════════════════════════════════
63
+ ```
64
+
65
+ 把 `Connect:` 整行复制到客户端的"远程连接"输入框即可，客户端会从 fragment 拆出 token。同样的内容也会落盘到 `~/.clawd/connect.txt`（0600）方便事后查阅。
66
+
67
+ 要换 register base url：`--clawos-api https://example.com`。
54
68
 
55
69
  启用后 daemon 会：
56
70
 
@@ -68,34 +82,14 @@ clawd --tunnel
68
82
 
69
83
  - 客户端连上后 5 秒内必须发送 `{"type":"auth","token":"<token>"}`
70
84
  - 通过 → daemon 回 `{"type":"auth:ok"}`
71
- - 失败/超时/越权 → close code 1008
85
+ - 失败 / 超时 / 越权 → close code 1008
72
86
 
73
87
  token 来源（任选其一）：
74
- - daemon 启动时 `Connect:` 那行整体复制（带 `#token=`），ext UI 一次粘贴即可
75
- - 单独从 `Auth Token:` 那行复制
88
+ - 启动 banner 里 `Connect:` 整行（带 `#token=`），客户端一次粘贴即可
89
+ - 单独从 `Auth Token:` 行复制
76
90
  - `~/.clawd/state.json` 的 `authToken` 字段（0600，仅本机用户可读）
77
91
 
78
- 非 tunnel 模式下 `127.0.0.1` / `::1` 来源连接默认豁免 auth（保持 1.0 体验）；`--tunnel` 模式所有连接都要 auth。
79
-
80
- ## 协议
81
-
82
- 完整方法与事件表见 [`../doc/clawd-protocol.md`](../doc/clawd-protocol.md)。
83
-
84
- - 所有请求帧 `{type, requestId, ...args}`，响应携带同一 `requestId`
85
- - session 事件默认推给订阅了该 sessionId 的客户端（`session:subscribe`）
86
- - `session:events({sessionId, afterSeq})` 拉缺口区间，支持刷新/重连后的 gap recovery
87
-
88
- ### Session 控制相关方法差异
89
-
90
- | RPC | 效果 | 进程存活 | 典型入口 |
91
- |---|---|---|---|
92
- | `session:stop` | **SIGTERM** 杀 claude 子进程（5s grace → SIGKILL），丢失 initialize / 预热缓存 | ✖ | 次级菜单（"Force Stop Process"） / ESC 双击升级确认 |
93
- | `session:interrupt` | 向 claude stdin 发 `control_request.subtype=interrupt`，取消当前轮次 | ✔ | 键盘 ESC 单次 / 输入框 ⏸ / 权限卡片 ⏸ |
94
- | `session:rewind` `{userMessageId, dryRun?}` | 发 `control_request.subtype=rewind_files`，回滚到指定 user message。`dryRun=true` 仅预览；`dryRun=false` 真回退并广播 `session:rewound` | ✔ | 历史 user message hover 的 "↶" 按钮 + 预览 Drawer |
95
-
96
- 两个新增事件：
97
-
98
- - `session:rewound { sessionId, userMessageId, at }` —— rewind apply 成功后广播；订阅该 sessionId 的客户端都会收到
92
+ 非 tunnel 模式下，`127.0.0.1` / `::1` 来源连接默认豁免 auth；`--tunnel` 模式所有连接都要 auth。
99
93
 
100
94
  ## 目录结构
101
95
 
@@ -103,44 +97,14 @@ token 来源（任选其一）：
103
97
  ~/.clawd/
104
98
  ├── config.json # 可选配置文件
105
99
  ├── state.json # 运行时发现文件（启动写，退出删）
106
- ├── clawd.log # 运行日志
107
- └── sessions/default/*.json # SessionFile 持久化
100
+ ├── auth.json # tunnel auth token 持久化
101
+ ├── tunnel.json # frps 凭证缓存
102
+ ├── connect.txt # tunnel 连接串
103
+ ├── frpc.toml / frpc.log # frpc 子进程配置 / 日志
104
+ ├── clawd.log # daemon 运行日志
105
+ └── sessions/default/*.json # 会话持久化
108
106
  ```
109
107
 
110
- ## 架构
108
+ ## License
111
109
 
112
- daemon 内部按 reducer + runner + dispatcher 三层拆分：
113
-
114
- ```
115
- WS frame / proc stdout
116
- │
117
- ▼
118
- SessionManager ─── reduceSession(state, input, deps) → {state', effects[]}
119
- │ （纯函数，无 side-effect；可 replay）
120
- │
121
- ├─► Effects runner（执行 spawn / write-stdin / kill / persist-file / emit-frame）
122
- │
123
- └─► dispatcher return {response, broadcast[]}
124
- │
125
- ▼
126
- transport（local-ws / remote-ws）
127
- ```
128
-
129
- - `src/session/reducer.ts`：纯函数，接收 `SessionInput`（stdout-line / proc-exit / command.* / permission-decision / tick）→ 返回 `{state, effects}`
130
- - `src/session/runner.ts`：Effect runner，执行副作用并把结果喂回 reducer
131
- - `src/session/manager.ts`：对外仅暴露 `handle(cmd): {response, broadcast[]}`；dispatcher 根据返回结果分发
132
- - `src/permission/permission.ts`：rule match 工具函数，不再有独立的 PermissionManager 类
133
- - 协议常量 / zod schema / METHOD_NAMES 统一从 `@clawos/clawd-protocol` 导入
134
-
135
- ## 零耦合承诺
136
-
137
- clawd daemon **不依赖** `openclaw-plugin-clawos`——不 import、不 copy、不共享路径。SessionStore / StreamParser / Permission / History 等均按 `../doc/clawd-protocol.md` 独立实现。
138
-
139
- ## 开发
140
-
141
- ```bash
142
- pnpm install
143
- pnpm build # tsc
144
- pnpm dev # tsx src/cli.ts
145
- pnpm test # vitest
146
- ```
110
+ MIT
package/package.json CHANGED
@@ -1,18 +1,10 @@
1
1
  {
2
2
  "name": "@clawos-dev/clawd",
3
- "version": "0.2.2",
3
+ "version": "0.2.3-beta.4.865defc",
4
4
  "description": "Standalone clawd daemon — Claude Code (and future Codex) session server over WebSocket",
5
5
  "type": "module",
6
6
  "license": "MIT",
7
- "homepage": "https://github.com/ottin4ttc/clawos/tree/main/clawd/daemon",
8
- "repository": {
9
- "type": "git",
10
- "url": "git+https://github.com/ottin4ttc/clawos.git",
11
- "directory": "clawd/daemon"
12
- },
13
- "bugs": {
14
- "url": "https://github.com/ottin4ttc/clawos/issues"
15
- },
7
+ "homepage": "https://clawos.chat",
16
8
  "publishConfig": {
17
9
  "access": "public"
18
10
  },