OpenClaw 配置与调试

概述

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

Bot 配对流程

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

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

已知配对记录

Bot	配对码	日期
wukong-bot	A3TYLKHV	2026-03-03
surface-wsl-bot	WE8PY55U	2026-03-04
gatewaybot	ZBZFX5D9	2026-03-17
kids	D3Z6TC7Z	2026-03-19
otter	7FDJPHDY	2026-03-19
healthbot	K68WUZUM	2026-03-28
craftbot	YZKWQ6D3	2026-03-17
	giraffe (Axolotl)	QS44965B
	portalbot	2QWJ8JRF
webbot	HPZ4D3YD	2026-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个，统一中文风格）

版本升级记录

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

Codex CLI 集成

GatewayBot（已淡出，现由 clawline-client-web Bot 维护）曾集成 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 诊断记录

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

斜杠命令不响应

Nexora 诊断了 Mattermost /new /status 等斜杠命令不响应的问题：

根因：OpenClaw 文档明确说明 native: "auto" 对 Mattermost 默认为 disabled，需设置 native: true 才能启用 native slash commands。但启用后仍需 Mattermost 服务器能回调到 Gateway。

回调可达性问题：Gateway 绑定 localhost:18789，Mattermost 服务器在 mm.dora.restry.cn 远程，无法回调到本地。

尝试方案（已回滚）：

配置 Caddy 反向代理 claw.nexora.restry.cn → Gateway:18789
设置 channels.mattermost.interactions.callbackBaseUrl 为该地址
被用户否决（安全风险：Gateway 暴露在公网），立即回滚

最终结论：不使用斜杠命令，改为在聊天中直接打文字（如 new session、status）。

Gateway 日志问题清单

级别	问题	说明
🔴	Mattermost 交互回调不可达	localhost:18789 远程不可达
🔴	grok-code-fast-1 模型不支持	GitHub Copilot provider 报 400
🟡	OpenRouter API Key 缺失	如不用可忽略
🟡	allowInsecureAuth=true	内网可接受，建议关闭
🟡	Bonjour 名称冲突	残留进程导致 mDNS 冲突
🟡	punycode 模块废弃	Node.js 内部，无害
🟡	pricing bootstrap failed	定价数据拉取失败，不影响使用

配对记录补充

Bot	配对码	日期
	bibot	MFRVEHQC
	nexora	FRZDA4GS

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：

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

Prism 五 Agent 配置详解（2026-03-13）

以下信息来源于 work_assistant 的 Mattermost DM 聊天记录。

多 Agent 架构配置

在 Eagle 服务器上部署了独立 OpenClaw 实例，配置 5 个 Agent 服务 Hackathon 团队：

Agent ID	Bot 账号	工作区	模型
prism-pm	@prism-pm	默认 workspace	claude-opus-4.6 (继承全局)
prism-arch	@prism-arch	workspace-prism-arch	gpt-5.4
prism-data	@prism-data	workspace-prism-data	claude-opus-4.5
prism-ui	@prism-ui	workspace-prism-ui	gemini-3.1-pro-preview
prism-docs	@prism-docs	workspace-prism-docs	gpt-5.2

关键配置要点

bindings 是路由关键：没有 bindings 配置，所有消息都会路由到 default agent。每个非默认 agent 需要 account → agent 的绑定
agentDir 不能放在 workspace 里：运行时数据（sessions、auth）应在 agents/<id> 而非 workspace-xxx/.openclaw
model 是字符串而非对象：直接 "model": "github-copilot/gpt-5.4"，不需要 {"primary": "..."}
groupAllowFrom 防死循环：用 groupPolicy: "allowlist" + groupAllowFrom: ["<人类用户ID>"] 限制群聊触发源

配置示例

{
  "agents": {
    "list": [
      {
        "id": "prism-pm",
        "default": true,
        "subagents": { "allowAgents": ["prism-arch", "prism-data", "prism-ui", "prism-docs"] }
      },
      {
        "id": "prism-arch",
        "model": "github-copilot/gpt-5.4",
        "workspace": "~/.openclaw/workspace-prism-arch",
        "agentDir": "agents/prism-arch",
        "subagents": { "allowAgents": ["prism-pm"] }
      }
    ]
  },
  "channels": {
    "mattermost": {
      "accounts": {
        "prism-pm": { "botToken": "..." },
        "prism-arch": { "botToken": "...", "groupAllowFrom": ["<人类用户ID>"] }
      },
      "bindings": [
        { "account": "prism-arch", "agent": "prism-arch" }
      ]
    }
  }
 
## Surface WSL Bot 配置经验
 
> 以下信息来源于 surface-wsl-bot DM 记录（2026-03-04 ~ 2026-03-22）。
 
### Windows 路径修复
WSL 环境中 openclaw.json 的 `agents.defaults.workspace` 被错误设为 Windows 路径 `C:\\Users\\micha\\.openclaw\\workspace`，导致在 `/home/restry/C:\Users\micha\.openclaw\workspace` 创建目录。修复为 Linux 路径 `~/.openclaw/workspace`。
 
### Mattermost 附件问题
附件无法接收的排查路径：
1. 插件双重加载（`plugins.load.paths` + `channels.mattermost`）→ 去掉 plugins.load.paths 中的 mattermost 条目
2. SSRF 保护拦截（Mattermost 域名解析为内网 IP）→ 关闭本地 DNS 解析，让域名走公网 IP
 
### Elevated 权限配置
```json
{
  "tools": {
    "elevated": {
      "enabled": true,
      "allowFrom": {
        "mattermost": ["all"]
      }
    }
  }
}

注意：修改此配置后需要重启 Gateway 才能生效，但重启 Gateway 又需要 elevated 权限——形成死循环。解决方案：用户在终端手动执行 openclaw gateway restart。

Agent 配置（5 Agent 体系）

{
  "agents": {
    "list": [
      { "id": "main", "name": "Jarvis", "model": { "primary": "github-copilot/claude-opus-4.6" }},
      { "id": "alpha", "workspace": "~/.openclaw/workspace/agents/alpha" },
      { "id": "gamma", "workspace": "~/.openclaw/workspace/agents/gamma" },
      { "id": "otter", "workspace": "~/.openclaw/workspace-otter" },
      { "id": "bnef", "workspace": "~/.openclaw/workspace-bnef" },
      { "id": "clawline", "workspace": "~/.openclaw/workspace-clawline" }
    ]
  }
}

已删除的 Agent：memory-distiller（smartExtraction 替代）、antfarm-medic（无实际用途）。

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

/status 输出快照

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

时间	版本	模型	Cache	Context
21:17	2026.4.2 (d74a122)	sweden-ext/gpt-5.4	100% hit, 56k cached	0/200k
22:02	2026.4.10 (44e5b62)	github-copilot/claude-opus-4.6	99% hit, 46k cached	80k/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

🔮 Dora's Wiki

探索