让助手住进团队的聊天里

验收清单

• openclaw gateway status 显示 Gateway 在跑，且监听的是 127.0.0.1:18789，不是 0.0.0.0。
• openclaw dashboard 能打开控制台，WebChat 里发消息能收到模型回复。
• 手机 Telegram 私聊 bot 能收到回复，且这条回复是经过 pairing 批准之后才出现的。
• 用另一个没批准过的 Telegram 账号发消息，助手不回应。
• 能说出 API Key 存在哪台机器上，以及为什么它没有离开这台机器。
• openclaw doctor 的输出里没有红色（error）级别的条目。

常见错误

openclaw 命令找不到（command not found）

安装脚本装完没有重新加载 shell，或全局 bin 目录不在 PATH 里。开一个新终端窗口再试；仍不行就先 node --version 确认 Node 版本满足 22.22.3+ / 24.15+ / 25.9+，再重跑安装。

Gateway 起不来，任何命令都报配置错误

配置是严格校验的：出现未知键或类型不对，Gateway 直接拒绝启动，只有诊断命令还能用。跑 openclaw doctor 看具体是哪一行，再 openclaw doctor --fix。被拒绝的写入会留成 <path>.rejected.<时间戳>，可以打开对照。

模型回 401 或提示配额不足

API Key 填错、过期或余额用光。用 openclaw config get 确认配置里读到的是哪个供应商，再回供应商控制台核对 Key 与余额。

Telegram 里发消息完全没反应

多数是 pairing 没批准，或 bot token 抄错。先 openclaw pairing list telegram 看有没有待批的配对码；再 openclaw channels status --probe 看渠道连通性；最后 openclaw logs 看有没有入站事件。

想先图省事，把 dmPolicy 直接设成 open

open 需要把 allowFrom 写成 ["*"]，等于任何人都能指挥一个能跑命令、能读写文件的助手。入门阶段一律保持默认的 pairing。

验收清单

• /context list 能看到 SOUL.md / AGENTS.md / USER.md 被注入，且没有出现截断提示。
• /new 开新会话后，助手仍记得你上一轮让它记住的偏好。
• openclaw memory search --query "<你写过的关键词>" 能检索到对应记忆条目。
• 工具策略生效：让助手做一件被 deny 的事，它做不到，而不是做了之后才报错。
• 危险命令会先走 exec 审批，openclaw approvals pending 里能看到这条待批记录。
• 把主模型的 Key 故意改错，助手能自动落到 fallbacks 里的备用模型继续回话。
• 两个人分别私聊助手，openclaw sessions --json 里能看到两条互相隔离的会话，内容不串台。
• 把这套配置交给一位没参与搭建的同事，他能照着你的说明用起来，不需要你在旁边解释。

常见错误

SOUL.md 写了很长，但助手说话没变化

多半被截断了，或者你没开新会话。工作区文件是会话开始时注入的，改完要 /new；再用 /context list 确认注入大小，超过 20000 字符的单文件会被截断留标记。

助手「忘了」你说过的话

上下文不等于记忆。上下文是这一次调用发出去的全部内容，记忆是写到磁盘的文件。没写进 MEMORY.md 或 memory/*.md 的，换个会话就没了——没有隐藏状态。

memory_search 检索不到东西

索引没建好或 embedding 没配。先 openclaw memory status 看索引与检索是否就绪，再 openclaw memory index --force 重建。

allow 里写了工具，助手还是用不了

工具可见性是逐层收紧的：base profile → provider profile → allow/deny，冲突时 deny 赢，且后面的层只能收紧不能放宽；沙箱会话还要再过 tools.sandbox.tools 一道。检查是不是上游某一层根本没放出这个工具。

多人用同一个助手，A 的私事出现在 B 的对话里

session.dmScope 还是默认的 main——所有私聊共享一个会话。改成 per-channel-peer（多账号再加一层用 per-account-channel-peer）。这个坑一旦发生就是数据泄露，不是体验问题，交付给别人用之前必须先做。

主模型限流，任务直接失败

没配 fallbacks。在 agents.defaults.model.fallbacks 按顺序写备用模型，主模型失败会自动往下试。

验收清单

• openclaw agents list --bindings 输出的路由和你写在纸上的预期完全一致，没有靠「试出来」的规则。
• 不可信 Agent 的命令确实跑在容器里：进容器和不进容器执行同一条命令，能看到文件系统不同。
• 定时任务连续三天在预期时间触发，openclaw automations runs --id <jobId> 里有对应的运行记录。
• 18789 端口在公网扫不到；远程访问只能经隧道或私有网络，且 gateway 鉴权已开启。
• openclaw backup create 生成的包能通过 openclaw backup verify，并且你在另一台机器上真的恢复过一次。
• 跑过一次 openclaw update，升级前后各留了一份备份，升级后 openclaw doctor --lint 通过。
• openclaw audit 能回答「上周谁让助手执行了哪类操作」，日志保留策略是明确写下来的。
• 配置写坏时你能在 10 分钟内恢复，且知道去哪找 .rejected.<时间戳> 文件。

常见错误

两个 Agent 的会话和认证状态互相污染

复用了同一个 Agent 目录。每个 Agent 必须有自己独立的目录与工作区，agents.entries 里逐个写清楚。

binding 写了但没生效

路由是最具体优先、同档位按配置顺序取第一个匹配。宽规则（只写 channel）排在窄规则（写到 peer）前面时，宽的先命中。把窄规则往前挪，再用 openclaw agents list --bindings 复核。

定时任务到点没跑

自动化跑在 Gateway 进程里，Gateway 没运行就不会触发。先 openclaw gateway status，再 openclaw automations runs --id <jobId> 看有没有失败记录，注意 --tz 有没有写对时区。

让 Agent 自己 sleep 轮询「等一会儿再提醒我」

会长期占住一条会话通道，还容易被超时看门狗杀掉。周期性与未来的事一律交给 automations，外部事件用 webhook，改运行时行为用 hook。

为了远程方便，把 Gateway 绑到 0.0.0.0

官方文档的原话是绝不要在 0.0.0.0 上暴露未鉴权的 Gateway——拿到这个端口等于拿到全部操作者权限。默认绑定就是 loopback，要扩到 lan 必须同时开 gateway 鉴权并加防火墙。

升级后行为变了，想回退却回不去

没有可恢复的备份。升级前 openclaw backup create 并 openclaw backup verify，而且至少在别的机器上恢复演练过一次——没演练过的备份不算备份。

用 openclaw doctor --fix 修配置，结果原文件被覆盖了

配置完全解析不了且没有可用备份时，doctor --fix 会把损坏文件保留成 openclaw.json.clobbered.<时间戳> 并报错退出，不会写半份配置。先去找这个文件，不要直接重写。