yangxuan/openclaw-config
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0b20494f7846e8c28a560d13dbbcd5579a6372ab
openclaw-config/docs/bk02-openclaw-系统说明.md
T

14 KiB
Raw Blame History

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 主机上执行）：

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. 服务与运维命令

# —— 必须的环境准备 ——
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）一致。

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 备份

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，否则提交永远不会上远端：

cd ~/.openclaw && git add -A && git commit -m "..." && git push origin 314

隐私红线：.gitignore 已加固，排除大体积/隐私数据：

workspace-*/data/
agents/*/session-sqlite-import-archive/

（曾发生 workspace-juaner/data/私聊_*.json 等被自动提交并推送到 Gitea，.git 一度涨到 199M。历史重写未做。）

8.3 回滚

# 服务定义
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 「页面打开慢 / 卡顿」

先分层定位，不要凭感觉：

# ① 服务端自身是否慢（应 <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 外网域名访问不了

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 可能不同。

/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 View Git Blame Copy Permalink