网关路由
Gateway HTTP 路由¶
本文介绍插件如何在 Gateway 上注册 HTTP 端点,以及这些路由所遵循的认证(auth)、作用域(scope)、替换(replacement)和准入(admission)规则。属于插件架构内部机制指南的一部分。
api.registerHttpRoute({
path: "/acme/webhook",
auth: "plugin",
match: "exact",
handler: async (_req, res) => {
res.statusCode = 200;
res.end("ok");
return true;
},
});
路由字段:
path:网关 HTTP 服务器下的路由路径。auth:必填,"gateway"或"plugin"。使用"gateway"要求正常的网关认证,或使用"plugin"进行插件管理的认证/Webhook 验证。match:可选。"exact"(默认)或"prefix"。handleUpgrade:可选,用于同一路由上 WebSocket 升级请求的处理程序。replaceExisting:可选。仅动态生命周期注册需要,用于替换其自身已有的路由。handler:当路由处理了请求时返回true。
注意事项:
api.registerHttpHandler(...)已被移除,使用它会引发插件加载错误。请改用api.registerHttpRoute(...)。- 插件路由必须显式声明
auth。 - 具有相同
match模式的规范等价路径只占一条路由。来自同一插件的静态api.registerHttpRoute(...)调用会替换该路由;其他插件无法替换它。 - 具有不同
auth级别的重叠路由会被拒绝。请仅在相同auth级别上保留exact/prefix回退链。 - 使用
openclaw/plugin-sdk/webhook-ingress中的registerPluginHttpRoute(...)进行动态生命周期编码时,必须设置replaceExisting: true才能刷新自身的规范路由。具名注册只能替换具有相同非空pluginId的路由;当任一侧设置了路由source时,两侧都必须设置相同的非空source。对于随附的 SDK 调用者,同一插件内无 source 到无 source 的刷新以及匿名到匿名的刷新仍然受支持,但具名路由和匿名路由不能相互替换。 - 设置
reuseExistingSameOwner: true可与具有相同非空pluginId和source的路由共享规范路由。动态创建的路由会一直保留,直到其最后一个持有者释放它;复用静态api.registerHttpRoute(...)路由时,其生命周期由插件注册表管理。 - 通道生命周期回调使用其 Gateway 的路由注册表。启动路由在其任务完成或恢复流程放弃该任务时过期;
stopAccount路由在该停止尝试完成或超时时过期。恢复流程会在替换启动之前撤销被放弃的任务路由,即使启动失败也是如此。已过期的回调不能动态注册或替换路由。 - 将路由
source视为同一插件内的稳定子所有者标识,而不是诊断标签。现有的无 source 调用者可以继续省略它;支持 source 的调用者必须在每次刷新时保持其不变。 - 默认情况下,动态生命周期注册在被拒绝时会记录日志并返回一个 no-op 注销回调。当就绪状态依赖该路由时,请设置
throwOnFailure: true;必需的捆绑 Webhook 传输使用严格注册,因此没有实时入口时它们无法报告就绪。 auth: "plugin"路由不会自动获得操作员运行时作用域。它们用于插件管理的 Webhook/签名验证,而非特权 Gateway 辅助调用。auth: "gateway"路由在 Gateway 请求运行时作用域内运行。默认表面(gatewayRuntimeScopeSurface: "write-default")刻意保持保守:- 共享密钥 Bearer 认证(
gateway.auth.mode = "token"/"password")以及任何非 trusted-proxy 认证方法都只会获得单个operator.write作用域,即使调用者发送了x-openclaw-scopes也是如此。 - 没有显式
x-openclaw-scopes请求头的trusted-proxy调用者也保留仅operator.write的旧版表面。 - 确实发送
x-openclaw-scopes的trusted-proxy调用者则会获得所声明的作用域。 - 路由可以选择
gatewayRuntimeScopeSurface: "trusted-operator",以便对承载身份信息的认证模式始终遵循x-openclaw-scopes(当请求头缺失时,回退到完整的 CLI 默认作用域集合)。 - 由
auth: "gateway"路由支撑的沙盒化外部 Control UI 标签页,使用仅由经过认证的引导过程签发的短期签名 Cookie 授权;plugin-auth 标签页则保持其直接的 iframe 路径。在挂载之前,父级会在同一个不透明沙盒内运行一次由路由拥有的检查;当浏览器隐私策略阻止 Cookie 时,默认采取失败关闭(fail closed)。该授权绑定到所属插件、匹配的路由根路径以及当前认证代次;其进程随机的 Cookie 名称可防止受信任的同主机 Gateway 互相覆盖,但 Cookie 永远无法隔离 TCP 端口。因此,Gateway 主机名构成一个凭据边界:不要在该主机名上共置互不信任的服务,包括其他端口。路由分发会拒绝针对另一插件拥有的嵌套路由进行复用。由于沙盒后代在 Cookie 意义上属于跨站(cross-site),该授权仅接受带operator.read的GET和HEAD;变更操作和 WebSocket 升级仍保留在显式 Gateway 认证的表面上。该 Cookie 有意不使用 CHIPS:当前浏览器会在分区键中包含跨站祖先位,因此嵌套的不透明沙盒框架将失去对同路由资源的访问。该 Cookie 需要安全上下文以及浏览器的跨站 Cookie 许可,因此 gateway-auth 外部标签页在纯 HTTP 局域网源或完全第三方 Cookie 阻止策略下不可用;请使用 HTTPS/Tailscale Serve 或浏览器信任的回环地址,并配合兼容的 Cookie 策略。 - 该授权可防止 Gateway Bearer 令牌泄露和意外路由/作用域复用;它并不会在原生插件之间建立安全边界。原生插件代码及其提供的 UI 内容仍属于同一个受信任的进程内插件边界。
- 实用规则:不要假定 gateway-auth 插件路由是隐式的管理表面。如果你的路由需要仅限管理员的(admin-only)行为,请选择
trusted-operator作用域表面,要求使用承载身份信息的认证模式,并记录显式的x-openclaw-scopes请求头契约。 - 启动插件会在 Gateway 开始监听后以其完整运行时注册 HTTP 路由。在启动 sidecar 就绪之前,未被认领的 HTTP 请求会返回带有
Retry-After: 1的503;核心路由继续正常分发。这个通用回退在运行时注册表能够识别插件路由的属主之前,覆盖这些插件路由。 - 在路由匹配和认证之后,普通处理程序会参与 Gateway 根工作准入。处于预备(prepared)或重启状态的 Gateway 会在调用处理程序之前返回
503。唯一的例外是:一条由 manifest 授权的auth: "gateway"路由同时选择了路由特定的trusted-operator表面;它保持可达,以便暂停控制分发不会被搁浅,而来自同一插件的普通兄弟路由仍停留在准入边界之后。WebSockethandleUpgrade的所有权使用相同的原子准入边界;一旦处理程序接受了 socket,该 socket 之后的生命周期由插件拥有,不受此边界跟踪。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw