Simi Studio
文章 标签 分类
Simi Studio

目录

OpenClaw 最佳实践

 收录于 AI 与自动化
   约 5581 字   预计阅读 12 分钟 

为什么重写这篇文章

OpenClaw 很强，但真正把它跑成一个稳定、常驻、可远程访问的 agent，难点通常不在“它支持多少渠道”，而在下面这些运维问题：

  1. 你是不是走了官方推荐的安装和升级路径。
  2. 你的 Gateway 到底暴露给了谁。
  3. 你的 skills、plugins、browser、node 有没有把风险面放大。
  4. 你升级后能不能快速验证、快速回滚。

这篇文章做两件事：

  1. 基于官方文档，整理一套更稳的部署与运维基线。
  2. 把我在真实部署里踩过的坑做脱敏总结，只保留可复用的结论和修复方法。

一页结论

如果你只想记住最关键的部分，看这一页就够了。

  1. 生产环境优先走官方安装和 openclaw onboard --install-daemon，不要把临时 source build 当成日常升级路径。
  2. 一个 Gateway 只服务一个信任边界。个人助手、团队助手、公开入口不要混在同一个高权限实例里。
  3. 默认坚持 gateway.bind: "loopback"，远程访问优先 SSH tunnel 或 Tailscale Serve，而不是直接对外监听。
  4. DM 默认用 dmPolicy: "pairing"，群组默认 requireMention: true，多人 DM 时打开 session.dmScope: "per-channel-peer"。
  5. Skills 和 plugins 都要按“可能执行代码”的标准对待；能 allowlist 就 allowlist，能 pin version 就 pin version。
  6. 更新优先 openclaw update，更新后固定执行 openclaw doctor、openclaw gateway restart、openclaw health。
  7. 健康检查不能只看进程活着，还要看渠道入站、消息闭环、日志脱敏和会话文件权限。

官方推荐的部署基线

1. 安装和初始化：先走官方路径

官方文档当前给出的推荐路径很明确：

curl -fsSL https://openclaw.ai/install.sh | bash
openclaw onboard --install-daemon
openclaw gateway status
openclaw dashboard

关键点有三个：

  1. Node.js 优先用 Node 24，Node 22.16+ 也支持，但官方推荐仍然是 24。
  2. openclaw onboard --install-daemon 是首选 bring-up 流程，它会把模型、Gateway 和常见认证路径一起配好。
  3. source checkout 更适合开发和调试，不适合代替大多数生产升级动作。

如果你只是想稳定运行 OpenClaw，而不是参与上游开发，尽量避免把“能跑起来的 source build”当成长期运维基线。

2. 先定义信任边界，再谈多 agent

OpenClaw 的官方安全模型不是“敌对多租户平台”，而是“个人助理 / 单一信任边界”。这意味着：

  1. 一个 Gateway 适合服务一个可信操作者边界。
  2. 如果是个人 bot、团队 bot、公开 bot 三种不同风险等级，最好拆成不同 Gateway，至少拆成不同 OS user / host。
  3. sessionKey、session label、channel binding 都是路由机制，不是权限边界。

这是很多部署一开始就偏离目标的地方。你以为“每个人各有 session”就已经隔离了，实际上高权限工具、浏览器、凭证、会话落盘，依然共享同一个宿主信任面。

3. 网络暴露面：默认 loopback，远程访问走 tunnel

官方文档对这件事讲得很直接：最稳的默认值就是 Gateway 只绑定本机回环地址，然后用 tunnel 或 tailnet 暴露给你自己。

一个适合生产起步的最小配置可以长这样：

{
  "gateway": {
    "mode": "local",
    "bind": "loopback",
    "port": 18789,
    "auth": { "mode": "token", "token": "${OPENCLAW_GATEWAY_TOKEN}" }
  },
  "session": {
    "dmScope": "per-channel-peer"
  },
  "channels": {
    "telegram": {
      "dmPolicy": "pairing",
      "groups": {
        "*": { "requireMention": true }
      }
    }
  }
}

这里有几条非常重要：

  1. gateway.bind: "loopback" 是默认安全姿势。
  2. gateway.auth.mode: "token" 或 "password" 要显式配置，不要假设“本机就不需要认证”。
  3. 非 loopback 绑定必须配认证和防火墙，不能裸奔到 0.0.0.0。
  4. 如果你用了反向代理，要正确配置 gateway.trustedProxies，并确保代理覆盖 X-Forwarded-For，而不是把不可信头原样拼接下传。

如果你只是想从另一台机器远程访问，最简单的 SSH tunnel 是：

ssh -N -L 18789:127.0.0.1:18789 user@host

然后本地 CLI 或 WebChat 继续连 ws://127.0.0.1:18789。

官方文档也明确提醒：gateway.remote.token / gateway.remote.password 是客户端访问远端 Gateway 的凭据来源，不等于服务端已经开启了认证。

4. DM、群组和上下文隔离：默认更保守

如果你的 bot 不是百分百只给自己用，那就不要一上来开 open。

官方建议里的几个关键开关值得直接照抄：

  1. DM 默认 dmPolicy: "pairing"。
  2. 群组默认 requireMention: true。
  3. 多人 DM 或共享收件箱场景，启用 session.dmScope: "per-channel-peer"。
  4. 需要更强约束时，给群组加 allowlist，不要靠“大家应该不会乱用”。

这套配置的价值不只是安全，还有可观测性。很多“bot 没回复”的问题，最终不是模型坏了，而是 pairing、allowlist 或 mention gate 在生效。

5. Skills、Plugins、Browser、Node 都算高影响面

OpenClaw 非常强大，但强大本身就是风险放大器。

官方文档里有几个结论，我建议你直接纳入自己的默认心智模型：

  1. Skills 和 plugins 都要按“可能执行代码”来对待。
  2. browser control 基本等价于“拿到了该浏览器 profile 能触达的一切”。
  3. paired node 上的 system.run 本质上就是远程执行。
  4. prompt guardrail 只是软约束，真正的硬边界来自 allowlist、tool policy、sandbox、exec approval 和 host isolation。

如果是多 agent 场景，推荐直接按 agent 分配不同访问级别：

  1. 私人高权限 agent：只给自己用，必要时可不启 sandbox。
  2. 团队/家人 agent：sandbox + 只读 workspace + 精简 tools。
  3. 公开入口 agent：禁文件系统、禁 shell、禁 browser、禁 cron、禁 gateway 工具。

6. 配置管理：严格校验是优点，不是麻烦

OpenClaw 的配置是严格 schema 校验的。未知字段、错误类型、非法值都会导致 Gateway 拒绝启动。

这对运维其实是好事，因为它能防止“配置看起来保存成功，实际上半生效”。

推荐做法：

  1. 新增配置优先参考官方 Configuration 和 schema。
  2. 改完配置先跑 openclaw doctor。
  3. 知道哪些配置是热更新，哪些会触发 restart。官方现在的默认 reload mode 是 hybrid。
  4. 不要把长期配置散落在多个 ad-hoc shell 启动参数里。

脱敏后的真实遇到问题总结

下面这些问题都来自真实部署，但我只保留对所有 OpenClaw 用户都有价值的部分。

1. 发布版 bundle 和 source build 不能混为一谈

这是我踩过的最典型的典型问题之一。

问题表象通常是这样的：

  1. 某个已发布版本的运行时有 bug。
  2. 你去看 source tree，觉得修复点很清楚。
  3. 你把本地 source build 或 tarball 直接塞进生产机，结果出现新的 bundle layout 漂移、运行时依赖缺失，或者行为和已发布版本并不一致。

根因在于：生产机跑的是“已发布产物”，不是你的本地源码目录。两者在 bundle 文件名、打包边界、内嵌依赖、插件布局上都可能不同。

更稳的处理方式是：

  1. 如果只是某个已发布 bundle 的局部 bug，优先对“正在工作的已发布产物”做最小、可回滚、可记录的补丁。
  2. 等官方新版本发布后，再回到标准更新路径。
  3. 只有当你明确决定把这台机器切到“自维护 source build 通道”时，才把 source checkout 当成长期运维基线。

一句话总结：生产修复要对准“生产正在跑的东西”，而不是对准“你手边最顺眼的源码树”。

2. Slash command 能注册成功，不代表运行时一定可执行

另一个高频坑是 skill 在 UI 或 slash command 列表里“看得到”，但真正调用时却像没注册一样。

最常见的根因有两个：

  1. 你把 skill 标成了 user-invocable: true，所以它会暴露为 slash command。
  2. 你同时又用了 disable-model-invocation: true，于是该 skill 不会进入模型 prompt。

如果这个 slash command 的执行仍然依赖模型读取 SKILL.md 指令，那它就会出现“命令存在，但执行不稳定甚至直接失败”的现象。

更稳的做法是：

  1. 如果命令本质上是 direct tool dispatch，就用 command-dispatch: tool 明确走工具直发。
  2. 如果命令仍需要模型理解 skill 指令，就不要把它从模型 prompt 中排除。
  3. 对关键 slash command 做端到端 smoke test，而不是只看“是否出现在命令列表里”。

3. Workspace skill 被发现了，不代表模型真正拿到了完整指令

某些版本或某些自定义 runtime 下，还会出现第二层问题：skill 虽然已经在 registry 里，但运行时只给模型一段很弱的提示，比如“请使用某个 skill 处理这个请求”，却没有把真正的 SKILL.md 指令体稳定注入进去。

这种情况下，结果往往取决于模型临场发挥，表现就会非常不稳定。

我后来总结出的经验是：

  1. 关键业务 skill 不要过度依赖“模型也许会自己去读”。
  2. 如果一个 skill 对确定性要求很高，要么改成 direct tool dispatch，要么确保运行时真的把 skill 内容注入了 prompt。
  3. skill 改完后，最好重开 session 或至少 reset 一次，不要假设旧 session 一定立刻拿到新快照。

官方文档也提到，skills 有 session snapshot 和 watcher 机制。热更新是有的，但对关键路径来说，“开新 session 验证一次”仍然更可靠。

4. 容器化部署最容易出现“看起来正常，实际上已经漂移”

真实运维里，容器启动成功只是第一步。真正麻烦的是配置漂移和运行时漂移。

我遇到过的典型问题包括：

  1. 宿主机回退场景和 sandbox 场景混用，结果 compose 文件越来越乱。
  2. 插件目录指向了源码路径，而不是编译产物路径，导致依赖重复加载或运行时冲突。
  3. bootstrap 没有显式 pin 默认模型，结果启动时吃进了旧 .env 或旧 .env.example 的遗留值。

更稳的做法是：

  1. 保持基础 docker-compose.yml 尽量通用和 sandbox-compatible。
  2. 宿主机特有差异放到独立 override 文件里。
  3. OpenClaw 的 bundled plugins 在容器里优先指向编译产物目录，而不是源码目录。
  4. 对 agents.defaults.model.primary 这类关键默认值显式写入，不要指望环境模板永远最新。

5. Skill 依赖要分别验证宿主和沙箱，而不是只看一边

官方 Skills 文档里有个很重要但很容易忽略的点：skill 的 requires.bins 是在宿主 load-time 检查的，但如果 agent 实际跑在 sandbox 里，对应二进制还必须存在于容器内部。

这意味着：

  1. “宿主机有这个命令” 不等于 “skill 在 sandbox 里可用”。
  2. 容器内缺 bin 时，很多 skill 会表现为“看起来可见，但调用时报错”。
  3. 真正稳的做法是通过 setupCommand 或自定义镜像把依赖装进 sandbox。

如果一个 skill 同时依赖外部命令和网络访问，还要额外确认 sandbox 的网络策略、根文件系统可写性、运行用户权限是否满足它的安装与执行方式。

6. 健康检查不能只看 Gateway process 还活着

这是另一个很常见的误判来源。

很多人看到 health endpoint 正常、容器 healthy、daemon 在跑，就以为整个系统没问题。但对 OpenClaw 来说，这最多只证明“Gateway 进程起来了”。

更靠谱的健康检查至少要分四层：

  1. 进程层：openclaw gateway status。
  2. 配置层：openclaw doctor。
  3. 渠道层：openclaw channels status --probe 或等价的 channel probe。
  4. 业务层：从真实聊天入口发一条测试消息，确认它真的能进来、能触发路由、能回消息。

如果你只做前两层，很容易漏掉 token 失效、channel 断链、allowlist 误配、mention gate 配错这类真正影响使用的问题。

7. 日志、会话、状态目录默认都应该视作敏感数据

官方文档对这件事讲得很清楚：~/.openclaw/ 下面不只有配置，还有 auth profile、pairing allowlist、session transcript、channel credential、secrets payload、sandbox 工作区等敏感数据。

最低限度应该做到：

  1. ~/.openclaw 权限控制在 700。
  2. ~/.openclaw/openclaw.json 权限控制在 600。
  3. 保持 logging.redactSensitive: "tools"。
  4. 对外分享诊断信息时，优先贴 openclaw status --all 这类已脱敏输出，不要直接扔原始日志。
  5. 在共享主机上尽量给 OpenClaw 单独的 OS user。

Skills 与插件的长期维护建议

这是 OpenClaw 运维里最容易“越用越乱”的一层。

Skill 位置和优先级要有明确约定

官方当前的 skill 加载优先级是：

  1. <workspace>/skills
  2. <workspace>/.agents/skills
  3. ~/.agents/skills
  4. ~/.openclaw/skills
  5. bundled skills
  6. skills.load.extraDirs

我的建议是：

  1. 项目专属 skill 放 <workspace>/skills。
  2. 机器级共享 skill 放 ~/.agents/skills 或 ~/.openclaw/skills，但不要两边重复定义同名 skill。
  3. 对关键 skill 维持清晰 ownership，避免“同名覆盖”排查地狱。

用 allowlist 管控 agent 能看到什么

skill 的“能被发现”与“能被某个 agent 使用”是两回事。

如果某个 agent 是公开入口或低权限入口，建议直接给它显式 skills allowlist，而不是默认继承全局 skills。

Plugins 运行在进程内，要比 skills 更谨慎

plugins 的风险面比普通 skill 更高，因为它们直接和 Gateway 进程同生命周期、同地址空间。

建议至少做到：

  1. 只装可信来源。
  2. 能 pin exact version 就不要用漂移的范围版本。
  3. 装完或更新后重启 Gateway。
  4. 定期跑 openclaw security audit 看插件扫描和 allowlist 状态。

升级、回滚与变更管理

官方推荐的升级流程

现在最推荐的升级命令是：

openclaw update

它会尝试识别你的安装方式，并在更新后跑 doctor 和 restart。更稳的人工流程可以是：

openclaw update --dry-run
openclaw update
openclaw doctor
openclaw gateway restart
openclaw health

几个实用点：

  1. --dry-run 很适合先看一眼将要发生什么。
  2. --channel beta 和 --tag beta 语义不同，前者更偏“优先 beta”，后者更像“强制这个 dist-tag”。
  3. auto-update 默认是关闭的，生产环境是否打开要看你对变更窗口的控制能力。

回滚要提前想好，而不是出问题时现编

如果你是 npm 安装，官方给的回滚方式很直接：

npm i -g openclaw@<version>
openclaw doctor
openclaw gateway restart

如果你是 source checkout，才考虑 pin 到某个 commit。也就是说：

  1. npm / install-script 路径适合“稳定生产 + 版本回滚”。
  2. source checkout 路径适合“自维护开发通道”。
  3. 两种路径不要在同一台生产机上频繁切来切去。

一套可执行的运维清单

最后给一份我自己认为最实用的 checklist。

上线前

  1. 确认安装路径是官方支持的，不是临时拼出来的 source build。
  2. 确认 gateway.bind 仍是 loopback，或者你已经配好了 token/password、防火墙、trusted proxy。
  3. 确认 DM 不是裸 open，群组已开启 mention gate。
  4. 确认 skills / plugins 来源清晰，关键 skill 已做 smoke test。
  5. 确认 browser 用的是独立 profile，不是你的日常主浏览器。
  6. 跑一次 openclaw security audit。

每次更新后

  1. 跑 openclaw doctor。
  2. 跑 openclaw gateway restart。
  3. 跑 openclaw health。
  4. 跑 channel probe。
  5. 从真实聊天入口发测试消息，验证完整闭环。

出现异常时

  1. 先判断是进程问题、配置问题、渠道问题，还是业务逻辑问题。
  2. 不要直接覆盖线上运行时，先对准“当前正在跑的产物”定位。
  3. 对外分享信息时用脱敏输出，不要直接贴原始 transcript 和 credential 路径。
  4. 如果怀疑暴露面过大，先回到 loopback、收紧 DM/group policy，再继续排查。

推荐阅读

如果你准备认真长期运行 OpenClaw，下面这些官方文档值得常驻书签：

  1. Getting Started
  2. Configuration
  3. Remote Access
  4. Security
  5. Skills
  6. Updating
  7. OpenClaw GitHub README

总结

OpenClaw 的价值不只是“把 AI 接到 Telegram / WhatsApp 上”，而是把模型、工具、渠道、状态和自动化放进一个你自己掌控的运行时里。

但也正因为它是真运行时，而不是一个纯聊天玩具，你必须把它当作一套长期在线系统来维护：

  1. 先守住官方安装和更新路径。
  2. 先守住 loopback、pairing、mention gate、tool policy 这些硬边界。
  3. 再去扩 skills、plugins、browser、nodes 这些高能力面。

如果你做到这三点，OpenClaw 才更像一个可靠的自托管 agent 平台，而不是一个“今天很神，明天就飘”的实验环境。

更新于 2026-04-10
 OpenClaw, AI Agent, 自托管, 运维, 最佳实践
返回 | 主页