docs: 结合 SORA 实践经验更新 onboarding 文档

bootstrap-onboarding: - 新增「从 Quick Tunnel 毕业到 Named Tunnel」章节 - macOS 远程登录补充具体路径 - --protocol http2 参数说明更新 - 新增踩坑 7：macOS 默认可能禁用密码 SSH onboarding-checklist: - Phase 5 更新工具名称和安装说明 - Phase 7 补充 A2A 双向验证提醒 - Phase 9 补充 SSH config ProxyCommand 模板 - Phase 11 补充 macOS Keychain 注意事项 - Phase 12 补充 Cursor API Key - 新增 Phase 14：运维与清理策略 - 注意事项补充 Session 累积警告
2026-03-30 17:47:44 +00:00 · 2026-03-30 17:47:44 +00:00 · 926dee307b
commit 926dee307b
parent ef55c7a096
2 changed files with 90 additions and 4 deletions
--- a/docs/shared/bootstrap-onboarding.md
+++ b/docs/shared/bootstrap-onboarding.md
@ -124,6 +124,9 @@ cloudflared tunnel --url tcp://localhost:22 --protocol http2

 命令执行后，cloudflared 会输出一个类似 `https://xxx-yyy-zzz.trycloudflare.com` 的临时域名。

+!!! info "`--protocol http2` 参数"
+    较新版本的 cloudflared 已默认使用 http2 协议，此参数可省略。如果你的 VPN/代理环境下遇到连接问题，可以显式加上确保不走 QUIC。
+
 !!! info "Quick Tunnel 的优势"
    - **零依赖**：不需要 Cloudflare 账号、不需要域名、不需要 Named Tunnel 配置
    - **零持久化**：隧道随进程启动/销毁，不留痕迹
@ -163,7 +166,7 @@ ssh -o ProxyCommand="cloudflared access tcp --hostname %h --url localhost:2222"
 |------|------|------|
 | 1 | 检测 OS 类型 | macOS/Ubuntu/Debian，选择对应包管理器 |
 | 2 | 安装 cloudflared | brew / apt / 直接下载二进制 |
-| 3 | 确认 SSH 服务运行 | macOS 需要手动开启"远程登录"，Linux 通常已启动 |
+| 3 | 确认 SSH 服务运行 | macOS 需要手动开启"远程登录"（系统设置 → 通用 → 共享 → 远程登录），Linux 通常已启动 |
 | 4 | 启动 Quick Tunnel | `cloudflared tunnel --url tcp://localhost:22 --protocol http2` |
 | 5 | 提取并显示隧道地址 | 解析 cloudflared stderr 输出 |
 | 6 | 等待 agent 接管 | 保持前台运行，Ctrl+C 可中断 |
@ -239,6 +242,16 @@ Bootstrap 场景优先用 Quick Tunnel。

 **注意**：这个 `cert.pem` 是 Cloudflare 专有的 Origin Certificate 格式，**不是**标准 X.509 证书。不能用 `openssl x509 -in cert.pem -text` 提取域名，命令会报错或输出乱码。这个文件只供 cloudflared 自身使用。

+### 7. macOS 默认可能禁用密码 SSH
+
+**问题**：部分 macOS 版本默认只允许公钥认证，不允许密码登录。Bootstrap 脚本依赖密码 SSH 进行首次连接。
+
+**解决方案**：
+
+1. 确认 `/etc/ssh/sshd_config` 中 `PasswordAuthentication` 设置（macOS 可能在 `/etc/ssh/sshd_config.d/` 下有覆盖文件，以最后生效的为准）
+2. 或者：人类在 bootstrap 前先把 buddy agent 的公钥手动加入 `~/.ssh/authorized_keys`
+3. 最可靠：脚本运行时提示人类输入 buddy agent 的公钥，自动写入 authorized_keys，完全绕过密码认证
+
 ---

 ## 安全考虑
@ -261,6 +274,61 @@ Bootstrap 场景优先用 Quick Tunnel。
 - 改用正式的、持久化的访问方式（Tailscale、固定公网 IP + 防火墙等）
 - 不要让 Quick Tunnel 长期运行，它是临时引导工具，不是生产访问方式

+---
+
+## 从 Quick Tunnel 毕业到 Named Tunnel
+
+Bootstrap 阶段用 Quick Tunnel 引导新设备，但**长期运行应切换到 Named Tunnel**。Quick Tunnel 的域名随进程随机生成，进程一旦退出隧道即失效，不适合作为持久访问入口。
+
+### Named Tunnel 的优势
+
+| 特性 | Quick Tunnel | Named Tunnel |
+|------|-------------|-------------|
+| 域名固定 | ❌ 每次随机 | ✅ 绑定你的域名 |
+| 可配置自启 | ❌ 手动运行 | ✅ cloudflared 作为系统服务 |
+| 不依赖进程存活 | ❌ 进程死则隧道断 | ✅ 服务化后自动重启 |
+| 需要 CF 账号 + 域名 | ❌ 不需要 | ✅ 需要 |
+
+### 切换步骤概要
+
+```bash
+# 1. 登录 Cloudflare（生成 ~/.cloudflared/cert.pem）
+cloudflared login
+
+# 2. 创建 Named Tunnel
+cloudflared tunnel create <tunnel-name>
+
+# 3. 编写配置文件
+cat > ~/.cloudflared/config.yml << 'EOF'
+tunnel: <tunnel-id>
+credentials-file: /home/<user>/.cloudflared/<tunnel-id>.json
+
+ingress:
+  - hostname: ssh.yourdomain.com
+    service: tcp://localhost:22
+  - service: http_status:404
+EOF
+
+# 4. 在 Cloudflare DNS 添加 CNAME 记录
+# ssh.yourdomain.com  CNAME  <tunnel-id>.cfargotunnel.com
+
+# 5. 安装为系统服务（可选，实现开机自启）
+sudo cloudflared service install
+```
+
+### SSH 场景示例
+
+切换到 Named Tunnel 后，在客户端的 `~/.ssh/config` 中配置 ProxyCommand，即可像普通 SSH 一样连接：
+
+```ssh-config
+Host my-server
+    HostName ssh.yourdomain.com
+    User youruser
+    ProxyCommand cloudflared access tcp --hostname %h --url localhost:%p
+```
+
+之后直接 `ssh my-server` 即可，无需手动启动代理进程。
+
 ### SSH 认证加固

 - Bootstrap 过程依赖密码 SSH，完成后应：
--- a/docs/shared/onboarding-checklist.md
+++ b/docs/shared/onboarding-checklist.md
@ -45,9 +45,9 @@
 ## Phase 5：开发工具链

 - [ ] GitHub CLI (`gh`) 安装
- [ ] copilot-cli 安装（如有订阅）
- [ ] cursor-agent 安装（如有订阅）
- [ ] claude-code 安装（如有订阅）
+- [ ] copilot-api 安装（如有订阅）<!-- 安装：npm i -g copilot-api 或源码编译 -->
+- [ ] Cursor Agent CLI 安装（如有订阅）<!-- 安装：curl https://cursor.com/install -fsS | bash -->
+- [ ] claude-code 安装（如有订阅）<!-- 安装：npm i -g @anthropic-ai/claude-code -->
 - [ ] 开发相关 CLI（docker, make 等按需）

 ## Phase 6：Skills 安装
@ -68,6 +68,7 @@
 - [ ] 配置 peers（与现有小队互联）
 - [ ] 现有小队的 peers 反向配置新成员
 - [ ] 双向 A2A 通信验证（ping-pong 测试）
+- [ ] ⚠️ 配完后务必双向验证（A → B 和 B → A 都测）。常见坑：token 配错只有单向通、新 token 覆盖了旧 token 导致其他 peer 失联

 ## Phase 8：网络与域名

@ -81,6 +82,13 @@
 - [ ] 新节点 → 现有节点 SSH 打通（新 agent 能 SSH 到 KUMA/NEKO 等）
 - [ ] 现有节点 → 新节点 SSH 打通（KUMA/NEKO 能 SSH 到新设备）
 - [ ] 验证双向 SSH 连通
+- [ ] 配置 `~/.ssh/config`（通过 Cloudflare Tunnel 的节点需要 ProxyCommand）：
+  ```ssh-config
+  Host <node-name>
+      HostName <node-domain>.shazhou.work
+      User <username>
+      ProxyCommand cloudflared access tcp --hostname %h --url localhost:%p
+  ```
 - [ ] 用途：跨节点救援、协作部署、故障恢复

 ## Phase 10：知识系统
@ -100,6 +108,7 @@
 - [ ] cloudflared Named Tunnel daemon 化 + 开机自启
 - [ ] 保活策略验证（KeepAlive / Restart=always）
 - [ ] 验证重启后所有服务自动恢复
+- [ ] ⚠️ macOS 注意：某些 CLI 工具（如 Cursor Agent）依赖 macOS Keychain，SSH 远程无法访问 GUI Keychain。需用户**本地终端**首次运行以解锁 Keychain 授权

 ## Phase 12：权限与凭证（留给新 agent 自行申请）

@ -112,6 +121,7 @@
 - [ ] SiliconFlow API Key（如需要）
 - [ ] npm Token（如需要发包）
 - [ ] 邮箱账号（如需要收发邮件）
+- [ ] Cursor API Key（如使用 Cursor Agent CLI）
 - [ ] 其他 API Keys（按需）

 ## Phase 13：Smoke Test
@ -124,6 +134,13 @@
 - [ ] Heartbeat 正常运行
 - [ ] 人类确认满意 ✅

+## Phase 14：运维与清理策略
+
+- [ ] 配置 session 定期清理（`openclaw sessions cleanup`），防止 A2A/subagent session 累积占内存
+- [ ] 了解 session 存储位置：`~/.openclaw/agents/<agent>/sessions/sessions.json`
+- [ ] 建议：将 `openclaw sessions cleanup` 加入 HEARTBEAT.md 或 cron 定期执行
+- [ ] 监控 Gateway 内存：大量 session 会导致 RSS 膨胀，定期清理可释放内存
+
 ---

 ## 注意事项
@ -133,3 +150,4 @@
 - **Auth 不代做** — 需要人类授权的事项留给新 agent 启动后自行申请
 - **每完成一个 Phase 汇报一次** — 让主人知道进度
 - **出错就停** — 不要带着错误继续，先修再推进
+- **Session 会累积** — A2A 和 subagent 每次通信都创建新 session，完成后不自动清理。长期运行务必定期 cleanup