跳转至

网关路由

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 表面;它保持可达,以便暂停控制分发不会被搁浅,而来自同一插件的普通兄弟路由仍停留在准入边界之后。WebSocket handleUpgrade 的所有权使用相同的原子准入边界;一旦处理程序接受了 socket,该 socket 之后的生命周期由插件拥有,不受此边界跟踪。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw