🔮 Dora's Wiki

OpenClaw 配置与调试

16分钟阅读

概述

OpenClaw 是 fries-mac Agent 的核心网关框架（233条消息），负责模型路由、会话管理、插件加载、Cron 任务调度等功能。调试过程中频繁遇到环境变量和命令路径问题。

Bot 配对流程

新 Bot 首次上线时需要完成 OpenClaw 配对：

  1. Bot 发送提示：“Please add me to teams and channels…”
  2. 用户发送消息后，Bot 返回配对信息（Mattermost user ID + Pairing code）
  3. Bot 所有者执行 openclaw pairing approve mattermost <code> 完成配对

已知配对记录

Bot配对码日期
wukong-botA3TYLKHV2026-03-03
surface-wsl-botWE8PY55U2026-03-04
gatewaybotZBZFX5D92026-03-17
kidsD3Z6TC7Z2026-03-19
otter7FDJPHDY2026-03-19
healthbotK68WUZUM2026-03-28
craftbotYZKWQ6D32026-03-17
giraffe (Axolotl)QS44965B
portalbot2QWJ8JRF
webbotHPZ4D3YD2026-03-17

关键事件

  • 2026-03-03: 首次启动时遇到 “Unknown model: github-copilot/gemini-3.1-pro-preview” 错误
  • 2026-03-03: 发现非交互式 shell 找不到 openclaw 命令，需加载 .zshrc
  • 2026-03-03: 成功修复后切换到 claude-opus-4.6 模型
  • 2026-03-03: 配置 memory-distiller agent 和 cron job（每小时蒸馏记忆）
  • 2026-03-10: 升级 AGENTS.md，增强心跳、可重入性、Memory Flush Protocol
  • 2026-03-11: wukong-bot 升级 OpenClaw 从 2026.2.6-3 到 2026.3.8 以解决无响应问题
  • 2026-03-21: 创建”研究员小薯条”子代理（researcher agent）
  • 2026-04-04: 查看和管理多个会话
  • 2026-04-07: 多节点版本快照 — flamingo 运行 4.1，Levis 从 3.28 升至 4.2 再到 4.5，cobra/tiger 运行 4.2，bear 仍在 3.12
  • 2026-04-07: Clawline 插件多次更新（git pull + gateway restart），修复 agentId 提取消息串扰、DM 路由 chatId 解析、文件 contentType 支持等
  • 2026-04-07: Bot/Agent 显示名批量重命名（main→Dora、research→研究员 等9个，统一中文风格）

2026-05-07 claw-bot OpenClaw v2026.4.1 schema 迁移：allowPrivateNetwork → network.dangerouslyAllowPrivateNetwork

claw-bot (192.168.1.235) 升 OpenClaw 后 systemd 进入 restart 循环（185 次），所有 agent config 加载失败。根因：v2026.4.1 schema 把 allowPrivateNetwork: true 这种顶层布尔字段挪进 network: { dangerouslyAllowPrivateNetwork: true } 子对象，旧 config 校验失败直接退出。

全机扫到 14 处 allowPrivateNetwork 残留（散落在多个 workspace 的 agent.yaml / plugin config）。修法：

  1. openclaw doctor --fix 一把扫描 + 自动迁移所有匹配字段（v2026.4.1 内置该 codemod）
  2. systemctl --user restart openclaw-gateway，restart 循环停止
  3. 手工 verify network.dangerouslyAllowPrivateNetwork 已成型，原顶层字段消失

教训：升级前先 openclaw doctor dry-run 看 schema diff；183+ restart loop 而 systemd 没退出 backoff 是因为 RestartSec=2s + StartLimitBurst 设得很宽松，建议生产改 StartLimitBurst=5 让进程及时停摆而不是黑屏循环。

5-07 → 5-08 后续：schema 修完 Mattermost 仍不回（fake-DNS 是误判，真因是 allowFrom 缺失）

claw-bot agent 起来后 Mattermost 消息依然静默无回复。从 ottor-laptop 远程经 claw@192.168.1.235（pwd `1qaz2wsx，注意反引号）登入逐项排查。

第一轮误判（已撤回）：本机 nslookup mm.cn.restry.cn 解析到 198.18.1.2，因为 198.18.0.0/15 是 RFC 2544 benchmark 段、典型 fake-IP 标志，初判为 Clash/V2Ray 类代理 fake DNS。但 5-08 复核发现：（a）公共 DNS（8.8.8.8、223.5.5.5）返回的也是 198.18.1.2，说明这是真实公网 A 记录而非本地伪造；（b）curl https://mm.cn.restry.cn/api/v4/system/ping 返回 200/88ms；（c）13 个 bot 全部 connected as @xxx，13 个 WebSocket ESTAB。网络层完全正常，fake-DNS 假说排除。

真正根因见下一节「dmPolicy: open 必须显式 allowFrom: ["*"]」。

教训：DNS 看到 198.18.x 不必然是 fake DNS（确实存在用此段做正常 anycast/CDN 落点的部署）；判定前先用公共 DNS 交叉解析、再 curl 实测应用层。WebSocket “连接 ESTAB 但收不到 event” 的最常见原因是应用层 ACL/订阅策略，不是网络层。

第二跳坑：dmPolicy: open 必须显式 allowFrom: ["*"]

allowPrivateNetwork 修完 gateway 起来了，但 mattermost 入站消息仍不到 bot。v2026.4.1 的另一个 schema 收紧：当 account dmPolicy: "open" 时，不再隐式允许所有发件人，必须显式声明 allowFrom: ["*"]（或具体用户白名单）。全机 14 处 mattermost account 配置批量补 allowFrom: ["*"]，13 个 bot 才正常收到 DM。

旧默认 = “open 即对所有人开放”；新默认 = “open 即不限会话发起方向，但发件人仍需走 allowFrom 校验”。语义没变但默认值翻了，无声破坏存量配置。

版本升级记录

日期Bot旧版本新版本原因
2026-03-11wukong-bot2026.2.6-3 (85ed6c7)2026.3.8 (3caab92)Bot 无响应
2026-04-07flamingo (cc-owl)2026.4.1 (da64a97)—当日状态（azure-foundry/gpt-5.4）
2026-04-07Levis (fires)2026.3.28 (f9b1079)2026.4.2 → 2026.4.5 (3e72c03)当日多次升级
2026-04-07cobra (nexora)2026.4.2 (d74a122)—当日状态
2026-04-07bear (cc-wolf)2026.3.12 (6472949)—当日状态
2026-04-07tiger (ottor)2026.4.2 (d74a122)—当日状态

注意: 升级最新版后部分开关/设置可能会被重置关闭

技术要点

  • 环境修复: 需在脚本开头显式 export PATH 或 source ~/.zshrc
  • Agent 创建: 通过 openclaw agents add 或 gateway config.patch
  • Cron 管理: openclaw cron add/runs 管理定时任务
  • AGENTS.md: 定义心跳策略、任务优先级、Memory Flush 协议
  • 多 Agent 架构: main + memory-distiller + researcher

经验教训

  • 非交互式 shell 是最常见的坑：必须 source ~/.zshrc 后才能使用 openclaw
  • openclaw cron add 不支持 --stagger 选项，要测试实际命令参数
  • Agent 配置变更后需要重启 Gateway
  • 子代理需要独立的工作区和 bot token

2026-05-07 OWL：systemd 跑 /usr/lib 旧版 vs ~/.local 新版（client chat.send sessionId schema 拒绝）

OWL 节点同时存在两份 OpenClaw：

路径版本来源
/usr/lib/node_modules/openclawv2026.4.5老的 sudo npm install -g（公网 npm public）
~/.local/lib/node_modules/openclawv2026.5.6用户 npm i -g（npm prefix=user）

systemd 默认指向 /usr/lib 跑 4.5；TUI / clawline channel 客户端走 PATH 拉到 ~/.local 5.6。client 的 chat.send 带 sessionId 字段（5.6 新加），4.5 schema 拒绝 → GatewayClientRequestError: invalid chat.send params: at root: unexpected property 'sessionId'，OWL 上的 outbound 全挂。同时启动日志报 Config was last written by a newer OpenClaw (2026.5.6); current version is 2026.4.5.

修法：systemd unit 显式指向 ~/.local/lib/node_modules/openclaw v2026.5.6，不要 sudo（用户 prefix 已生效，sudo 反而污染 /usr/lib）。重启后 sessionId 字段 + version 警告同时消失。

副作用：clawcraft 插件先前因为 5.6/4.5 双装在启动期疯狂重复注册 52 次（每次 config hot-reload 触发），内存爆到 340MB。版本对齐后只剩 1 plugin (clawline)，再也不刷日志。

v2026.5.6 自身的 npm beta channel 打包 bug：dist/extensions/{acpx,discord}/runtime-api.js 等 sidecar 文件缺失，安装时报 missing bundled runtime sidecar。是 OpenClaw 官方包问题，不是本地。手工补装相关 sidecar 可绕。

详见 decisions 5-07 OWL 段。

Codex CLI 集成

GatewayBot 集成了 Codex CLI 作为主力编码工具：

  • 版本：v0.115.0（从 0.114.0 升级）
  • 模型：gpt-5.4 (Azure OpenAI)
  • Session 机制：每次 codex exec 创建新 session，可用 codex exec resume <session-id> 或 codex exec resume --last 恢复
  • 固定开销：启动时加载 repo 文件结构和 git 状态约 12k tokens
  • 持久记忆：支持 ~/.codex/memories/ 目录下 markdown 文件
  • 典型耗费：admin-new UI 集成任务耗费约 259k tokens
  • 经验：简单测试看着性价比低（12k tokens 只回一句话），但复杂任务中 base cost 占比很小

相关主题

详见 Nexora Gateway 诊断记录。

BNEF Bot（prism-pm）高级配置

以下信息来源于 bnef 的 Mattermost DM 聊天记录（2026-03-13）。

BNEF Bot 展示了 OpenClaw 的高级配置能力：

Elevated 权限配置

{
  "tools": {
    "elevated": { "enabled": true },
    "exec": { "host": "gateway", "security": "full", "ask": "off" }
  }
}

注意：allowFrom.generic-channel 未配置（安全考虑），elevated 仅在 gateway 直接运行时可用。

Chatmode 配置

prism-pm 使用 onchar 模式配合 oncharPrefixes: ["pm"]，使得群消息以 pm 开头即可触发。其他 4 个 Agent 使用默认 oncall 模式（需 @mention）。

模式行为
oncall群里 @mention 才响应（默认）
onmessage群里每条消息都响应
onchar消息以指定前缀开头才响应

Skill 创建流程

BNEF Bot 创建了 azure-devops skill：

  1. 读取 skill-creator 规范
  2. 编写 SKILL.md（含触发条件：提到 Azure DevOps、ADO、代码仓库等）
  3. 安装到 OpenClaw（workspace/skills/azure-devops/）
  4. 连接信息（URL + PAT）、Git 认证、REST API 操作、az CLI 配置均封装在技能中

详见 Prism 五 Agent 配置详解。

详见 Surface WSL Bot 配置经验。

2026-04-11 更新：状态检查、模型切换与 Gateway 重启

/status 输出快照

两次 /status 检查记录了 OpenClaw 版本演进：

时间版本模型CacheContext
21:172026.4.2 (d74a122)sweden-ext/gpt-5.4100% hit, 56k cached0/200k
22:022026.4.10 (44e5b62)github-copilot/claude-opus-4.699% hit, 46k cached80k/200k (40%)

版本从 4.2 升级到 4.10，模型从 Azure gpt-5.4 切换到 GitHub Copilot Claude Opus 4.6。

模型切换操作

  • /models — 查看所有 provider（5 个 Azure + 1 个 github-copilot）
  • /models github-copilot — 列出 provider 下所有模型（15-20 个）
  • /model github-copilot/claude-opus-4.6 — 切换当前模型
  • /think high — 设置思考等级

Gateway 重启

更新 azure provider 配置（apiKey 轮换 + eaips provider 添加）后，需重启 gateway 生效。重启过程中 researcher agent 两次超时。

Provider 配置管理

通过 openclaw.json 的 models.providers 管理 provider 列表。本次操作：

  • 更新 azure-openai provider 的 baseUrl 和 apiKey
  • 新增 eaips provider
  • 重命名 eaips → eaips-sweden、liwei-eastus2 → eaips-eastus2
  • 同步更新 memory 插件的 embedding baseURL

2026-04-12 更新

  • 修复了 ~/.acpx/config.json 中 claude 适配器配置错误（指向普通 CLI 脚本而非 ACP 适配器）
  • 正确的内置适配器应使用 npx @zed-industries/claude-agent-acp@0.21.0
  • 发现 ACP cwd 参数在 persistent 模式下可能因复用旧 session 而不生效

2026-04-18 更新（ottor-laptop）

npm 包升级

包旧新
openclaw2026.4.22026.4.15 (commit 041266a)
clawhub0.7.00.9.0
openclaw-tavily0.2.1已最新

ClawTeam-OpenClaw（fork）

HKUDS/ClawTeam 的 fork ClawTeam-OpenClaw（作者 win4r）— 多 agent 群体协调框架，让多个 CLI coding agent（OpenClaw、Claude Code、Codex、Hermes Agent、nanobot、Cursor 等）自组织成团队分工。它 bundle 了 OpenClaw 作为默认 agent，与 npm 安装的 openclaw 本体是两个东西。

2026-04-28 更新（ottor-laptop）

Gateway 异常停止 — 不是 crash 是 SIGTERM

clawline 插件不响应。诊断 openclaw-gateway.service enabled 但 inactive。systemd journal 显示 20:28-20:34 这 6 分钟里被反复 stop 三次（没有 exit-code / signal=KILL / Failed），最后一次没起回来。判定为人为或脚本主动 systemctl stop。前一段进程 CPU 累计 1h39min、内存峰值 3.1G（lancedb-pro 是吃内存大头）。修法 systemctl --user start openclaw-gateway.service，因 enabled 重启机器自动起。

memory-lancedb-pro 升级 1.1.0-beta.9 → beta.10

来源是 GitHub CortexReach/memory-lancedb-pro（不是 npm registry — registry 上 1.0.32 是另一条老分支）。tag v1.1.0-beta.10（“OpenClaw 2026.3+ Hook Adaptation”，2026-03-23）。

踩坑：第一次把旧版备份目录留在 ~/.openclaw/extensions/ 同级，OpenClaw 启动扫描 extensions/ 下所有目录，把备份当 duplicate plugin id 加载，字母序在后还覆盖了新版。修：备份挪到 ~/.openclaw/_backups/ 干净。

遗留：lancedb-pro 配的 Azure embedding key 仍 401（同 04-26 sweden-ext key 轮换那次，详见 eaips-provider-migration）；lossless-claw context-engine 注册不上（info.id must match registered id），降级到 legacy engine 跑。OpenClaw 本体 2026.4.15 → 2026.4.26 也有更新。

经验

  • OpenClaw 扫 extensions/ 是无脑 listdir。任何备份/wip/*.bak 目录都不能放在 extensions/ 同级，否则会被当 plugin 加载并按 id 顺序覆盖正常版本。备份位置：~/.openclaw/_backups/。
  • Gateway 看似”挂了”先看 systemd 日志，不要先怀疑 crash —— 多数情况是被某个 script 主动停的。

2026-04-29 更新（ottor-laptop）

Gateway 14:03 SIGTERM → 删 memory-lancedb-pro 切 memory-core

openclaw-gateway.service 14:03:36 收到 SIGTERM 正常退出（exit 0）后没人拉起。死前 log 有：

  • memory-lancedb-pro recall failed: Azure OpenAI 404 Resource not found（embedding endpoint）
  • Context engine "lossless-claw" factory returned an invalid ContextEngine

curl 直连 text-embedding-3-large 端点 200，配置里 apiKey 也是 84 字符真值不是 mask —— 根因不明（疑 Sweden 区抖动 + 插件 URL 拼接 bug 叠加）。直接把 memory-lancedb-pro 从 allow / entries / slots.memory 全清掉，gateway 自动 fallback 到已配置的 memory-core（lcm.db），记忆功能没断。备份在 ~/.openclaw/openclaw.json.bak.before-rm-lancedb-*。

新增 provider copilot-proxy（Eagle 中转）

把 Eagle Copilot Proxy 接进 OpenClaw，绕开本机 GitHub Copilot 直连：

baseUrl: https://api.eagle.openclaws.co.uk/v1
api: openai-completions
authHeader: false
models: 16  (gpt-5.5 / 5.2-codex / 5.1 / 5.1-codex / 5.1-codex-max / 5-mini /
              claude-opus-4.7-1m-internal / 4.7 / 4.6 / 4.5 /
              sonnet-4.6 / 4.5 / haiku-4.5 /
              gemini-3.1-pro-preview / 3-flash-preview / grok-code-fast-1)

写入命令是 openclaw config set models.providers.copilot-proxy '{...}' --strict-json（不是 openclaw config patch，那个不存在）。坑：openclaw models set copilot-proxy/gpt-5.5 设默认后，/models 里只看得到这一个；其余 15 个要逐个 openclaw models fallbacks add copilot-proxy/<id> 加白名单，否则 /model 切换报”不允许”。

新机器一键脚本（pure bash heredoc，不依赖 python）已沉淀，写到机器上 EAGLE_PROXY_KEY=... 一行即可。

Claude Code 技能调参

调用 Claude Code 的技能默认改成：

claude -c --model claude-opus-4.7-1m-internal --effort high --dangerously-skip-permissions -p "..." < /dev/null

effort 档位 low / medium / high / xhigh / max（全实测，无 auto）。⚠️ 命令行参数是 --effort 不是 --reasoning-effort，曾踩坑。

2026-05-04 更新（ottor-laptop）

provider rename copilot-proxy → eagle

ottor-laptop 上把 Eagle Copilot Proxy 接入的 provider key 从 copilot-proxy 改名为短名 eagle，一条 jq 完成 provider key + agents.defaults.model.primary + fallbacks + models 全替换（备份到 ~/.openclaw/openclaw.json.bak.eagle）。新机器一键脚本（heredoc + EAGLE_API_KEY=...，幂等）已沉淀到 skill。结果：default = eagle/gpt-5.5，27 fallbacks 含 15 条 eagle/*，44 configured models 含 16 条 eagle/*。

Allowlist 真正的源 = agents.defaults.models 的 keys

调试过程中确认了 04-29 那条”fallbacks 里要逐个 add 才能切”的本质：buildAllowedModelSet() 直接读 params.cfg.agents?.defaults?.models 这个 map 的 keys 当 allowlist。fallbacks 里的也会被顺手加入，但正确做法是把模型 key 放进 models map，不是塞进 fallbacks（fallbacks 表达”主模型挂了用哪个降级”，不该作为开放清单的入口）。

gpt-5.5 仅暴露在 responses endpoint

eagle 上 gpt-5.5 的真实 model id 是 gpt-5.5-2026-04-23，只走 /v1/responses，/v1/chat/completions 不通。provider 配 api: "openai-completions" 是给其余 chat 模型用的，不影响 gpt-5.5（OpenClaw 自动选端点）。

关系图谱

反向链接