跳转到内容

OpenClaw 生产实践:插件、消息队列、部署与回滚

OpenClaw 生产部署先明确它代表谁、能做什么,再讨论插件和消息功能。 一个 Gateway 默认对应一个可信操作者边界,不是对抗性多租户隔离层。Tool、Plugin、Channel 和 Cron 都能持续产生影响,权限、状态目录和恢复步骤必须与功能一起设计。

OpenClaw 是自托管的多渠道 AI Gateway,把模型、会话、工具、Skills、插件和消息渠道组织在长期运行的进程中。本文按“上手 → 扩展 → 队列 → 部署 → 升级”组织,固定机制注明版本;协议专项排障与记忆系统仍保留独立文章。

1. 最短上手:先记录版本,再跑通一次请求

Section titled “1. 最短上手:先记录版本,再跑通一次请求”

安装并检查版本:

Terminal window
npm install -g openclaw@latest
openclaw --version

运行交互式配置并安装后台服务:

Terminal window
openclaw onboard --install-daemon

确认 Gateway,并发起一次 Agent 请求:

Terminal window
openclaw gateway status
openclaw agent --message "用三点总结当前工作区状态"

复制后续示例前,先核对实际安装版本的命令和配置:

Terminal window
openclaw --version
openclaw help
openclaw doctor

不要只在文档里写 latest。教程和排障记录还应保存 Node.js、操作系统、模型 Provider、协议、关键配置、成功与失败输出及最后验证日期。

2. 先选扩展层级:Skill、Tool、Hook、Plugin 与 Slot

Section titled “2. 先选扩展层级:Skill、Tool、Hook、Plugin 与 Slot”

Skill、Tool、Plugin 与 Hook 的落点

机制谁触发适合什么
Skill构建上下文时加载教 Agent 一类任务的流程、约束和领域知识
Tool模型按需调用搜索、计算、文件处理、外部 API 等一个具体动作
Hook命令或生命周期事件发生/new、/reset 自动化和工作区级小脚本
PluginGateway 运行时加载生命周期干预、能力注册、配置 Schema 和打包分发
Slot替换排他性核心能力接管 memory 或 contextEngine 等核心管线

选择标准是“哪一层刚好覆盖需求”,不是 Plugin 更高级。只增加操作步骤用 Skill,只增加一个动作用 Tool,需要事件控制或完整扩展包才用 Plugin。

Plugin 运行在 Gateway 进程内,与 Gateway 共享权限。 安装它就是引入代码,不是增加一个普通配置项。依赖树、来源、加载路径和 allow / deny 都要审查。

一个插件最小目录:

my-plugin/
├── openclaw.plugin.json
├── package.json
└── index.ts

openclaw.plugin.json 声明插件身份与配置 Schema,package.json 声明入口,index.ts 注册实际能力。

{
"id": "my-plugin",
"configSchema": {
"type": "object",
"properties": {
"apiKey": { "type": "string" }
}
}
}
{
"name": "my-plugin",
"openclaw": {
"extensions": ["./index.ts"]
}
}

配置校验可以基于 manifest 和 JSON Schema 完成,不必先执行插件代码。一个包的 openclaw.extensions 也可以导出多个入口,形成 plugin pack。插件 ID 是稳定接口:同一 ID 的冲突会影响配置归属、加载控制和排障。

常用注册能力包括:

API用途
api.registerTool(...)暴露给模型调用的函数
api.on(...)注册类型化 Agent 生命周期钩子
api.registerService(...)启动时初始化资源,关闭时释放,运行后台 watcher
api.registerHttpRoute(...)注册 webhook 或插件私有 HTTP 接口,显式处理认证和冲突
api.registerProvider(...) / api.registerChannel(...)接入模型 Provider 或消息渠道

下面组合了 Tool、Prompt 构建和 Service。它是固定版本文档的说明性示例,实际插件需按安装版本的 SDK 编译验证:

import { Type } from "@sinclair/typebox";
export default function register(api) {
api.registerTool({
name: "say_hello",
label: "Say Hello",
description: "Return a greeting",
parameters: Type.Object({ name: Type.String() }),
async execute(_toolCallId, params) {
return {
content: [{ type: "text", text: `Hello, ${params.name}!` }],
};
},
}, { name: "say_hello" });
api.on("before_prompt_build", async () => ({
prependSystemContext: "Be concise and technical.",
}));
api.registerService({
id: "my-plugin-service",
start: (ctx) => ctx.logger.info("plugin started"),
stop: async (ctx) => ctx.logger.info("plugin stopped"),
});
}

生命周期顺序决定能否读到 messages

Section titled “生命周期顺序决定能否读到 messages”
钩子时机适合什么
before_model_resolvesession load 之前按确定规则覆盖模型或 Provider
before_prompt_buildsession load 之后、模型调用前根据当前消息动态拼接上下文
before_agent_startlegacy compatibility hook新逻辑应拆到上面两个,不当万能入口

顺序是:

before_model_resolve
→ session load
→ before_prompt_build
→ legacy before_agent_start fallback
→ 真正发起模型调用

before_prompt_build 可以使用 prependSystemContext、appendSystemContext、systemPrompt 等能力。它是高权限扩展点,运维侧可以限制单个插件的 Prompt 注入能力:

plugins.entries.<plugin-id>.hooks.allowPromptInjection: false

Slot 只在你准备接管整条链路时使用

Section titled “Slot 只在你准备接管整条链路时使用”

普通插件是在旁边加能力,Slot Plugin 是替换核心实现:

{
"plugins": {
"slots": {
"memory": "memory-core",
"contextEngine": "legacy"
}
}
}

memory 控制长期记忆插件,contextEngine 控制 session context 的 ingest、assembly 和 compaction。先写顺普通插件,确认默认实现哪里不够,再考虑替换;记忆系统的默认机制见OpenClaw 记忆系统拆解。

开发期可用 plugins.load.paths 指向本地目录,运行期应使用明确的包版本,并配置 allow / deny、entries 和 slots。

冷态 list / inspect 只证明磁盘和配置层面发现了插件;带 --runtime 的 inspect 才能说明运行中的 Gateway 实际注册了什么。出现“列表里有但不生效”时,先区分发现、加载和注册三个阶段。

4. Agent 忙着时,新消息按意图进入不同路径

Section titled “4. Agent 忙着时,新消息按意图进入不同路径”

一个 session 同时只允许一个 run 执行。run 是从读取上下文、调用模型和工具到回复用户的完整过程。串行化是为了避免两边同时追加对话和交叉工具结果。

if (session.hasActiveRun) {
handleWithQueueMode(message)
} else {
startNewRun(message)
}

hasActiveRun 成立时,四种模式分别这样处理:

用户意图模式新消息去向
当前方向没错,只补充条件steer送进当前 run,改变后续判断
当前完成后,每条消息单独回答followup当前 run 结束后,每条各开一轮
连续补充同一件事的几段材料collect等安静窗口后合并,只开一轮
当前任务已经错了,需要停止interrupt取消当前 run,再执行最新消息

用户补一句“只读检查,别改文件”,steer 会在结构安全的位置把新消息写入上下文。模型发出 tool call 后,记录里必须出现对应的 tool result,不能简单把用户消息插在两者中间。

固定到 OpenClaw 2026.7.1-2,随包文档把注入点放在当前工具调用批次结束后;滚动文档已把检查推进到工具启动边界。两者共同的边界是:已经开始的工具不会被 steer 回滚,新消息会在下一次模型判断前出现。当前运行时不支持 steering 时,则等当前 run 结束后再执行。

followup 一次从队列取一条,一条消息开一个 run;collect 默认再等 500ms 安静窗口,把同路由的连续消息合成一个 prompt,只开一个 run。

所谓同路由,要比较 channel、thread、接收目标、账号和回复位置。不同投递目标不能合并,否则 A 线程的问题可能回到 B 线程。

interrupt 向当前 run 发出 abort,并清掉尚未开始的工作,当前 run 退出后再执行最新消息。已经修改的文件、发出的消息和提交的数据库事务不会自动恢复,工具需要自己支持取消检查、幂等或补偿。

稳定版的默认队列上限为 20 条,默认 drop:summarize 只把被移除消息压成受长度限制的文本预览,不会额外调用模型。/queue 设置优先级为:会话内设置 > 渠道设置 > 全局设置。

/queue steer
/queue followup
/queue collect debounce:0.5s cap:25 drop:summarize
/queue interrupt
/queue reset

稳定版 followup 队列保存在进程内 Map 中。必须跨重启处理的业务消息,不能只依赖这个内存队列,要在渠道接入层或业务层持久化。

5. 生产部署先收紧信任和暴露范围

Section titled “5. 生产部署先收紧信任和暴露范围”

官方安全模型是个人助手信任模型:一个 Gateway 面向一个可信操作者边界。多个互不信任的用户共享 Tool-enabled Agent,也会共享 Agent 被授予的工具权限。

多用户或多组织场景应拆成:

独立 Gateway + 独立凭证 + 独立状态目录
+ 独立 OS 用户或主机 + 独立网络与资源限制

sessionKey 用于路由会话,不是授权令牌。

优先保持 loopback,通过 Tailscale Serve 或等价可信隧道远程访问。必须使用 lan、tailnet 或 custom 时,同时配置:

  • Gateway token 或 password;
  • 真实防火墙和来源限制;
  • Control UI allowed origins;
  • 不暴露无认证反向代理路径;
  • 不把 Canvas 与特权控制面放在不可信同源环境。

修改网络、Channel 或 Tool 配置后运行:

Terminal window
openclaw security audit
openclaw security audit --deep
openclaw security audit --json

--fix 只应用官方定义的安全修复,执行前检查 diff,不能把它当成通用加固按钮。

处理网页、邮件或陌生用户内容时,默认拒绝控制面敏感工具,再按任务开放。重点检查 Slash Command 发送者、Channel 通配符、system.run、Cron、跨会话工具、文件范围、Browser 与网络 egress,以及发信、付款和删除的审批。

.env、认证 Profile 和 Gateway token 不进入 Git;文件权限限制到运行用户;容器升级保留状态目录;不要把宿主 Docker Socket 挂进 Agent Sandbox;日志开启脱敏并定期轮换长期凭证。

Terminal window
curl -fsS http://127.0.0.1:18789/healthz
curl -fsS http://127.0.0.1:18789/readyz
openclaw health

探针通过只说明进程和服务状态。真正验收还要走通:

Channel 收到消息
→ Agent 正确路由
→ Tool 在预期权限内执行
→ 用户收到结果
→ Trace 和日志可以还原过程

6. 升级与回滚都要验证状态格式

Section titled “6. 升级与回滚都要验证状态格式”

升级前保存当前版本、配置校验和、插件与 Skill 版本、状态目录快照、镜像 digest 或安装包版本,以及一组最小验收任务。

升级后依次验证:

  1. Gateway 启动;
  2. Security Audit;
  3. Channel 登录状态;
  4. 模型调用;
  5. 关键 Tool;
  6. 定时任务;
  7. 新消息队列模式;
  8. 重启后的状态恢复。

回滚不能只降低二进制版本,还要确认配置和状态格式兼容。发布前至少确认:可信边界唯一、暴露范围明确、认证和防火墙启用、审计无未解释高风险项、Tool 与 Channel 使用 allowlist、凭证不入库、状态目录可恢复、真实业务验收通过、回滚已演练。