docs: 增补 bk02 openclaw 系统说明与文档索引（新会话接手入口）
This commit is contained in:
@@ -0,0 +1,17 @@
|
|||||||
|
# bk02 openclaw 文档目录
|
||||||
|
|
||||||
|
> 本目录存放**本机 OpenClaw 系统**的运维文档。
|
||||||
|
> **新会话 / 新人接手请先读第 1 份**，无需依赖任何历史对话。
|
||||||
|
|
||||||
|
| # | 文档 | 内容 |
|
||||||
|
|---|---|---|
|
||||||
|
| 1 | `bk02-openclaw-系统说明.md` | **接手入口**：主机与访问、架构、关键路径速查、服务与运维命令、存储结论（SQLite-only）、配置与凭据位置、插件、备份/回滚/Git 仓库、**排查手册**、已知边界与坑 |
|
||||||
|
| 2 | `openclaw-升级与维护.md` | 2026-09-16 升级实测记录：Node 22.23.1→26.8.2、OpenClaw 2026.8.1→2026.9.4、清理 4.6G、踩坑清单、回滚步骤 |
|
||||||
|
|
||||||
|
## 目录约定
|
||||||
|
|
||||||
|
1. **不含明文口令**：仅记录凭据的存放位置（见系统说明 §6）；备份包含凭据，勿外发。
|
||||||
|
2. **文档是快照**：版本、磁盘占用、插件清单等会变化，下判断前先用命令核对（首选 `openclaw doctor`）。
|
||||||
|
3. **改动后要推送**：本目录属于 `~/.openclaw` 这个 git 仓库（分支 `314`、remote 为 Gitea）。
|
||||||
|
该仓库的 `auto-commit-config.sh` 在「无变更」时会**直接退出、不推送**，因此**手动提交后必须自己 `git push origin 314`**。
|
||||||
|
4. **新增文档**：按 `序号` 或明确主题命名，并登记到本文件。
|
||||||
@@ -0,0 +1,330 @@
|
|||||||
|
# bk02 openclaw 系统说明
|
||||||
|
|
||||||
|
> **用途**：本机 OpenClaw 系统的总说明。**新会话 / 新人接手请先读本文件**，无需依赖任何历史对话。
|
||||||
|
> **配套**：`openclaw-升级与维护.md`（2026-09-16 升级 Node 22→26 与清理 4.6G 的实测记录）
|
||||||
|
> **主机**：bk02 / `xuan-asus-nj` · Debian 12 bookworm · 更新时间 2026-09-16
|
||||||
|
>
|
||||||
|
> ⚠️ 本目录**不含明文口令**，凭据位置见 §6。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 0. 30 秒速览
|
||||||
|
|
||||||
|
| 项 | 值 |
|
||||||
|
|---|---|
|
||||||
|
| 服务 | `openclaw-gateway.service`（**用户级** systemd，必须用 `systemctl --user`） |
|
||||||
|
| 版本 | OpenClaw **2026.9.4** (3a9d69d) |
|
||||||
|
| 运行时 | nvm **Node v26.8.2**（**不要**用系统 `/usr/bin/node` 22.x，版本不够） |
|
||||||
|
| 本机监听 | `127.0.0.1:18789`（+ `[::1]:18789`），不对外暴露 |
|
||||||
|
| 访问入口 | **`https://bk02.baiji-algieba.ts.net`**（tailscale serve，仅 tailnet 内可达） |
|
||||||
|
| 状态目录 | `~/.openclaw`（约 1.5G） |
|
||||||
|
| 存储 | SQLite（**不支持** PostgreSQL/MySQL，见 §5） |
|
||||||
|
|
||||||
|
**最常用的三条命令**（都在 `~/.openclaw` 主机上执行）：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
export NVM_DIR=$HOME/.nvm; . $NVM_DIR/nvm.sh; nvm use 26 # 每次登录先做，否则 openclaw 命令不在 PATH
|
||||||
|
|
||||||
|
openclaw doctor # 健康检查（问题与修复建议都在这里）
|
||||||
|
journalctl --user -u openclaw-gateway -f # 实时日志
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. 主机与访问
|
||||||
|
|
||||||
|
| 项 | 值 |
|
||||||
|
|---|---|
|
||||||
|
| 主机名 | `xuan-asus-nj`（tailnet 名 `bk02`） |
|
||||||
|
| 系统 | Debian GNU/Linux 12 (bookworm)，内核 6.1.0-50-amd64 |
|
||||||
|
| 内网 IP | `192.168.3.14`（enp4s0f2） |
|
||||||
|
| tailscale IP | `100.115.195.192` |
|
||||||
|
| 登录用户 | `yangxuan`（凭据由机主掌握） |
|
||||||
|
| 磁盘 | 根分区 109G，当前约 24G（23%） |
|
||||||
|
| 内存 | 7.6G（gateway 进程 RSS ≈ 580MB） |
|
||||||
|
| 容器 | postgres(pgvector)、mysql、clash（docker，与 openclaw 无耦合，可作 agent 工具数据源） |
|
||||||
|
|
||||||
|
**从 wit01 的实测链路**：`tailscale ping bk02` → `via DERP(lian) ≈ 23ms`，**非直连**（wit01 侧 `MappingVariesByDestIP: true`，对称 NAT）。因此经 tailscale 访问比局域网直连多约 120ms/请求，属正常现象。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. 架构
|
||||||
|
|
||||||
|
```
|
||||||
|
浏览器 / App
|
||||||
|
│ https://bk02.baiji-algieba.ts.net ← tailscale serve 在 443 终止 TLS
|
||||||
|
▼
|
||||||
|
本机回环 127.0.0.1:18789 ← openclaw gateway（node 进程）
|
||||||
|
│
|
||||||
|
├─ 配置 ~/.openclaw/openclaw.json
|
||||||
|
├─ 状态 ~/.openclaw/state/openclaw.sqlite （共享状态）
|
||||||
|
├─ 会话 ~/.openclaw/agents/<id>/agent/openclaw-agent.sqlite （每 agent 一个）
|
||||||
|
├─ 插件 ~/.openclaw/npm/projects/<plugin>/
|
||||||
|
└─ 工作区 ~/.openclaw/workspace*/ （agent 的文件空间）
|
||||||
|
```
|
||||||
|
|
||||||
|
| 组件 | 说明 |
|
||||||
|
|---|---|
|
||||||
|
| gateway | `openclaw .../dist/index.js gateway --port 18789`，启动约 **14.5s**（首次更久） |
|
||||||
|
| tailscale serve | `gateway.tailscale.mode = serve`，gateway 启动时自动声明/恢复 HTTPS 路由 |
|
||||||
|
| 前端 | Control UI（HTTP/2 + Brotli，压缩后约 348KB，9 个资源） |
|
||||||
|
| 协议 | HTTP + WebSocket（UI 的所有数据与操作走 WS RPC） |
|
||||||
|
|
||||||
|
**ExecStart 实际内容**：
|
||||||
|
|
||||||
|
```
|
||||||
|
/home/yangxuan/.nvm/versions/node/v26.8.2/bin/node --max-old-space-size=3913 \
|
||||||
|
/home/yangxuan/.nvm/versions/node/v26.8.2/lib/node_modules/openclaw/dist/index.js \
|
||||||
|
gateway --port 18789
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. 关键路径速查
|
||||||
|
|
||||||
|
| 用途 | 路径 |
|
||||||
|
|---|---|
|
||||||
|
| 主配置 | `~/.openclaw/openclaw.json` |
|
||||||
|
| 环境变量/密钥 | `~/.openclaw/.env` |
|
||||||
|
| 共享状态库 | `~/.openclaw/state/openclaw.sqlite` |
|
||||||
|
| agent 会话库 | `~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite` |
|
||||||
|
| 迁移归档 | `~/.openclaw/agents/<id>/session-sqlite-import-archive/`（**保留，勿删**，见 §10） |
|
||||||
|
| 日志（文件） | `/tmp/openclaw/openclaw-YYYY-MM-DD.log` |
|
||||||
|
| 日志（journal） | `journalctl --user -u openclaw-gateway` |
|
||||||
|
| 插件安装目录 | `~/.openclaw/npm/projects/` |
|
||||||
|
| 备份归档 | `~/openclaw-backups/*.tar.gz` |
|
||||||
|
| 服务定义 | `~/.config/systemd/user/openclaw-gateway.service` |
|
||||||
|
| 本目录（文档） | `~/.openclaw/docs/` |
|
||||||
|
| 配置 git 仓库 | `~/.openclaw/.git`（分支 `314`） |
|
||||||
|
|
||||||
|
**agent 清单（12 个）**：`main` `note` `tab` `sql` `pbs` `wellness` `finances` `fitness` `resume` `travel` `juaner` `openclaw`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. 服务与运维命令
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# —— 必须的环境准备 ——
|
||||||
|
export NVM_DIR=$HOME/.nvm; . $NVM_DIR/nvm.sh; nvm use 26
|
||||||
|
|
||||||
|
# —— 生命周期 ——
|
||||||
|
openclaw gateway start
|
||||||
|
openclaw gateway restart
|
||||||
|
openclaw gateway stop --force # 不加 --force 会被拒绝（保护性设计）
|
||||||
|
systemctl --user status openclaw-gateway
|
||||||
|
systemctl --user is-active openclaw-gateway
|
||||||
|
|
||||||
|
# —— 健康与诊断 ——
|
||||||
|
openclaw doctor # 总健康检查 + 修复建议
|
||||||
|
openclaw doctor --fix # 应用修复（会迁移遗留文件、轮转配置备份）
|
||||||
|
openclaw status
|
||||||
|
openclaw plugins list
|
||||||
|
openclaw sessions --all-agents
|
||||||
|
|
||||||
|
# —— 备份（改动前必做）——
|
||||||
|
openclaw backup create --verify --output ~/openclaw-backups
|
||||||
|
|
||||||
|
# —— 离线维护（必须先停 gateway）——
|
||||||
|
openclaw doctor --session-sqlite compact --session-sqlite-all-agents
|
||||||
|
openclaw doctor --state-sqlite compact --json
|
||||||
|
|
||||||
|
# —— 升级 ——
|
||||||
|
openclaw update status # 看当前版本与可用版本
|
||||||
|
openclaw update --dry-run --yes # 预览计划
|
||||||
|
openclaw update --yes # 执行（注意 Node 版本要求，见 §9）
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. 存储：只能用 SQLite
|
||||||
|
|
||||||
|
**官方结论**（`openclaw update` 相关文档原文）：
|
||||||
|
|
||||||
|
> *SQLite remains the supported runtime store. Preparation for PostgreSQL should improve the existing store owners and their tests **before adding a driver or configuration option**.*
|
||||||
|
|
||||||
|
| 检查 | 结果 |
|
||||||
|
|---|---|
|
||||||
|
| 存储实现 | Node 内置 `node:sqlite`（无外部数据库依赖） |
|
||||||
|
| 官方文档 `mysql` / `mariadb` | **0 次命中** |
|
||||||
|
| 代码里的 PostgreSQL/MySQL 字样 | 来自 **SQL 语法高亮方言**与报错文案，**非存储后端** |
|
||||||
|
| 表结构示例 | `session_nodes` / `transcript_events` / `session_transcript_archives`(BLOB) / `memory_index_*` 等 |
|
||||||
|
| 库规模（2026-09-16） | 共享状态库 12.7MB；各 agent 库合计约 143MB；共 36 个库 |
|
||||||
|
|
||||||
|
**推论**：本机 docker 的 postgres/mysql **不能**替代 openclaw 的存储；但可以经 `sql-toolkit` 等工具**给 agent 当数据源**（配置里已有 `"MySQL":{"enabled":true}`），两者是不同层面。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. 配置与凭据
|
||||||
|
|
||||||
|
| 项 | 位置（不记录明文） |
|
||||||
|
|---|---|
|
||||||
|
| gateway 认证 | `openclaw.json` → `gateway.auth`（`mode: password`） |
|
||||||
|
| 允许来源 | `gateway.controlUi.allowedOrigins` |
|
||||||
|
| 受信代理 | `gateway.trustedProxies`（含 tailnet 段） |
|
||||||
|
| 模型/渠道密钥 | `~/.openclaw/.env` + `openclaw.json` 的 `secrets` 段；systemd 通过 `OPENCLAW_SERVICE_MANAGED_ENV_KEYS` 注入 |
|
||||||
|
| 主机登录 | 由机主掌握（ssh `yangxuan@bk02`） |
|
||||||
|
| 备份包 | `~/openclaw-backups/*.tar.gz`（**含凭据，勿外发**） |
|
||||||
|
|
||||||
|
**配置备份环（官方机制，勿手删）**：
|
||||||
|
|
||||||
|
```
|
||||||
|
openclaw.json ← 当前配置
|
||||||
|
openclaw.json.bak / .bak.1 … .bak.4 ← 每次配置写入自动轮转的备份环
|
||||||
|
openclaw.json.last-good ← 解析失败时的自动恢复源
|
||||||
|
openclaw.json.pre-update ← 升级前快照
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. 插件与渠道
|
||||||
|
|
||||||
|
安装位置 `~/.openclaw/npm/projects/`，版本应与核心（2026.9.4）一致。
|
||||||
|
|
||||||
|
```bash
|
||||||
|
openclaw plugins list
|
||||||
|
openclaw plugins update <name> # 同步到当前核心版本
|
||||||
|
openclaw plugins uninstall <name> --force # 注意是 --force（无 --non-interactive 参数）
|
||||||
|
openclaw daemon install # 服务定义重建（会顺带修正 Node 路径）
|
||||||
|
```
|
||||||
|
|
||||||
|
常见插件：`feishu`、`searxng`、`deepseek`（provider）、`openclaw-weixin`、`dingtalk-connector`、`memory-core`、`ollama`。
|
||||||
|
渠道（钉钉/微信等）在 gateway 启动日志中会打印 `starting ... provider` 与 `client ready`。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 8. 备份、回滚与 Git 仓库
|
||||||
|
|
||||||
|
### 8.1 备份
|
||||||
|
|
||||||
|
```bash
|
||||||
|
openclaw backup create --verify --output ~/openclaw-backups
|
||||||
|
```
|
||||||
|
|
||||||
|
- **`--verify` 必须能通过**才算可靠备份
|
||||||
|
- ⚠️ 若 workspace 下存在**仅大小写不同**的重复目录（曾发生 `skills/Obsidian` 与 `skills/obsidian`），会因 *portable path collision* 导致验证失败 → 用 `diff -r` 确认后把重复项移出（`mv` 到备份区，不要 `rm`），再重新备份
|
||||||
|
|
||||||
|
### 8.2 配置仓库（Gitea）
|
||||||
|
|
||||||
|
| 项 | 值 |
|
||||||
|
|---|---|
|
||||||
|
| 仓库 | `~/.openclaw`（本身是 git 仓库，分支 `314`） |
|
||||||
|
| remote | `https://gitea.climbcube.cn/yangxuan/openclaw-config.git` |
|
||||||
|
| 自动提交 | `auto-commit-config.sh`，每 6 小时 `git add -A` + commit + push |
|
||||||
|
| 提交信息 | `auto: sync OpenClaw config <时间>` / `auto: agent DB backup <日期>` |
|
||||||
|
|
||||||
|
**手动提交注意**：该脚本在 `git status` 为空时会**直接退出、不 push**。因此手动提交后**必须自己 push**，否则提交永远不会上远端：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd ~/.openclaw && git add -A && git commit -m "..." && git push origin 314
|
||||||
|
```
|
||||||
|
|
||||||
|
**隐私红线**：`.gitignore` 已加固，排除大体积/隐私数据：
|
||||||
|
|
||||||
|
```gitignore
|
||||||
|
workspace-*/data/
|
||||||
|
agents/*/session-sqlite-import-archive/
|
||||||
|
```
|
||||||
|
|
||||||
|
（曾发生 `workspace-juaner/data/私聊_*.json` 等被自动提交并推送到 Gitea，`.git` 一度涨到 199M。历史重写未做。）
|
||||||
|
|
||||||
|
### 8.3 回滚
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 服务定义
|
||||||
|
cp ~/.config/systemd/user/openclaw-gateway.service.bak ~/.config/systemd/user/openclaw-gateway.service
|
||||||
|
systemctl --user daemon-reload && systemctl --user restart openclaw-gateway
|
||||||
|
|
||||||
|
# 版本回退（注意：nvm v25.9.0 与旧 openclaw 已于 2026-09-16 删除，需重新下载）
|
||||||
|
nvm install 25.9.0 && nvm exec 25.9.0 npm i -g openclaw@2026.8.1
|
||||||
|
```
|
||||||
|
|
||||||
|
数据恢复用 `~/openclaw-backups/` 里的验证备份。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 9. 排查手册（按症状查）
|
||||||
|
|
||||||
|
### 9.1 「页面打开慢 / 卡顿」
|
||||||
|
|
||||||
|
**先分层定位，不要凭感觉**：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# ① 服务端自身是否慢（应 <10ms）
|
||||||
|
curl -o /dev/null -s -w "code=%{http_code} ttfb=%{time_starttransfer}s\n" http://127.0.0.1:18789/
|
||||||
|
|
||||||
|
# ② 服务端 RPC 耗时统计（WS RPC 是 UI 的数据通道）
|
||||||
|
journalctl --user -u openclaw-gateway --since "10 min ago" --no-pager \
|
||||||
|
| grep -oE 'res ✓ [a-zA-Z.]+ [0-9]+ms' | sort -t' ' -k3 -rn | head -15
|
||||||
|
|
||||||
|
# ③ 是否落在 gateway 重启后的冷启动窗口
|
||||||
|
cat ~/.openclaw/logs/gateway-restart.log; journalctl --user -u openclaw-gateway --since "5 min ago" | grep -i started
|
||||||
|
```
|
||||||
|
|
||||||
|
判断基线（2026-09-16 实测）：
|
||||||
|
|
||||||
|
| 层 | 正常值 | 异常信号 |
|
||||||
|
|---|---|---|
|
||||||
|
| 服务端首页 | 本地 **4–5ms** | > 500ms |
|
||||||
|
| WS RPC | 稳态 **60–300ms**，无 >1s 调用 | 出现 1.5–4.4s 的一批调用 ⇒ **gateway 刚重启**（冷启动约 20s，之后恢复） |
|
||||||
|
| 前端资源 | 压缩后 348KB，9 资源并发 **0.16–0.8s** | — |
|
||||||
|
| 链路 | 经 DERP 中继，多约 120ms/请求 | — |
|
||||||
|
|
||||||
|
> **常见误判**：把"页面卡"归因于"数据/缓存太多"。实测 `main` 库仅 37MB、transcript 1327 行、会话 6 个 —— 数据量很小，磁盘 23%。若服务端 RPC 正常，**卡顿通常在浏览器渲染侧**（同时打开的面板越多、订阅越多，重渲染越重）。
|
||||||
|
|
||||||
|
### 9.2 服务不响应 / 502
|
||||||
|
|
||||||
|
1. `ss -tlnp | grep 18789` —— 无监听说明进程没起来
|
||||||
|
2. `systemctl --user is-active openclaw-gateway`
|
||||||
|
3. `journalctl --user -u openclaw-gateway -n 100` —— 看是否在启动中（**启动需约 14.5s**）
|
||||||
|
4. 启动后确认日志出现 `[gateway] ready`
|
||||||
|
|
||||||
|
### 9.3 外网域名访问不了
|
||||||
|
|
||||||
|
```bash
|
||||||
|
tailscale serve status # 确认 443 → 127.0.0.1:18789 映射存在
|
||||||
|
journalctl --user -u openclaw-gateway | grep -i 'serve enabled'
|
||||||
|
```
|
||||||
|
|
||||||
|
gateway 重启会自动重新声明路由，日志应出现：
|
||||||
|
`[tailscale] serve enabled: https://bk02.baiji-algieba.ts.net/`
|
||||||
|
|
||||||
|
### 9.4 SQLite 相关
|
||||||
|
|
||||||
|
- 维护类命令（`compact`）**必须先停 gateway**，否则会因占用锁被拒绝
|
||||||
|
- 若 `wal_checkpoint` busy：确认没有残留子进程或其它 SQLite 维护命令在跑
|
||||||
|
- 健康检查看 `integrityCheck`（应 `ok`）与 `freelistPages`（应 `0`）
|
||||||
|
|
||||||
|
### 9.5 升级前必查（Node 版本陷阱）
|
||||||
|
|
||||||
|
新版本对 Node 有硬性要求，例如 2026.9.4 要求 `>=24.16.0 <25 || >=26.1.0` —— **注意 25.x 被整体排除**。
|
||||||
|
gateway 用的是 `ExecStart` 里**硬编码的 node 绝对路径**，与登录 shell 的 node 可能不同。
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/usr/bin/node --version # 系统 node（升级前是 22.23.1，不够用）
|
||||||
|
nvm exec default node --version # 当前默认
|
||||||
|
grep '^ExecStart' ~/.config/systemd/user/openclaw-gateway.service # 服务实际用的
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 10. 已知边界与坑（重要）
|
||||||
|
|
||||||
|
| 事项 | 说明 |
|
||||||
|
|---|---|
|
||||||
|
| **迁移归档勿删** | `agents/*/session-sqlite-import-archive/`（约 525MB）是 2026-08-31 会话迁入 SQLite 时的原始归档。官方 `openclaw update cleanup` **拒绝清理**（`historical-manifest-without-import-proof`）。已验证它们**不是运行时依赖**（`session_transcript_archives` 表用 BLOB 存内容、不引用文件路径），删除**不影响运行**，但会**永久失去降级回旧 JSONL 版本的能力** ⇒ 目前**保留** |
|
||||||
|
| **数据库不可替换** | 见 §5，PostgreSQL/MySQL 均不支持 |
|
||||||
|
| **npm 11 拦 install scripts** | 全局安装 openclaw 时须带 `--allow-scripts=openclaw,@google/genai,koffi,tree-sitter-bash,protobufjs`，否则原生模块不构建（koffi / tree-sitter-bash） |
|
||||||
|
| **配置备份环勿手删** | `.bak` `.bak.1~4` `last-good` `pre-update` 均为官方机制 |
|
||||||
|
| **skill 重名冲突** | 日志中 `Skill precedence collision`（workspace 覆盖 bundled）属**设计内优先级行为**，非错误 |
|
||||||
|
| **skill 必须有 frontmatter** | 新版要求 `SKILL.md` 顶部有 YAML `name` + `description`，否则日志报 `Skipping invalid skill` 并跳过 |
|
||||||
|
| **改动后要重启** | 插件变更、skill 变更需 `openclaw gateway restart` 才生效 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 11. 新会话接手顺序
|
||||||
|
|
||||||
|
1. **本文件**（系统全貌、路径、命令、排查）
|
||||||
|
2. `openclaw-升级与维护.md`（2026-09-16 升级与清理的完整实测过程、踩坑与回滚）
|
||||||
|
3. 需要时用 `openclaw doctor` 获取当前真实状态（文档是快照，doctor 是实时）
|
||||||
|
|
||||||
|
**信息时效**：本文数据取自 2026-09-16 实测；版本、磁盘、插件清单等会变化，判断前请用命令核对。
|
||||||
Reference in New Issue
Block a user