网关 HTTP API
网关在提供本地 CLI 的同时还暴露了 REST 接口。凡是可以通过 zeroclaw config get/set/list/init/migrate 设置的内容，都可经由 HTTP 访问，因此仪表盘、第三方工具和 CLI 都会驱动同一套底层的 Config 变更核心。
本页面提供高层概览。当前文档化 OpenAPI 子集的字段级定义、请求和响应结构，以及“试用”表单，位于运行中网关的 /api/docs。这些架构来自运行时类型，但路由清单是单独构建的，目前尚未涵盖网关注册的每条路由。crates/zeroclaw-gateway/src/lib.rs 中的路由器仍是完整实际接口面的权威来源。
在 issue #6175 下跟踪。
身份验证
此页面描述的配置值读取和变更受现有配对和 bearer 身份验证保护。通过 /api/docs、/api/openapi.json 和配置 OPTIONS 进行的结构发现是公开的。守护进程启动时会打印首次运行配对码；后续已认证调用会在 Authorization 标头中发送派生的 bearer 令牌。/api/docs 上的 Scalar explorer 提供一个 “Authentication” 面板，你可以在发起已认证调用前粘贴令牌。
默认绑定本地。通过网络访问需要在网关处或其前端进行 TLS 终止；无论 TLS 配置如何，单属性端点和 PATCH 端点都不适合在未经身份验证的情况下暴露。
Channel 插件 Webhook 入口
构建时启用 WASM 插件支持后，当正在运行且已显式配置的通道插件声明了某个路径时，网关会暴露 GET 和 POST /plugin/{path}。这是一个原始传输边界：网关会将 HTTP 方法、原始查询字符串、请求体字节以及小写的 UTF-8 请求头保存到带类型的请求中，并传递给组件的 parse-webhook 导出函数。组件使用其作用域密钥验证平台请求，然后返回标准化的消息或明确的挑战应答。该请求不会内联执行智能体轮次，应答也不会进入智能体队列。
声明的路径必须由 1 至 64 个 ASCII 字母、数字、连字符或下划线组成。重复或无效的声明者会在守护进程原子性地发布其运行时路由映射之前被拒绝。
| 状态 | |Public body 公共机构| |-| | 含义 |
|---|---|---|
200 | 空文本或挑战文本 | 经过验证的请求会投递已授权的消息、忽略重复消息和被拒绝的发送者，或返回一个不超过 4096 个 UTF-8 字节的仅响应式挑战。 |
| 400 | invalid webhook | 客户机已验证该请求的身份，但拒绝了其载荷结构。 |
| 401 | 未授权的 webhook | 访客平台真实性验证失败。 |
| 404 | webhook not found | 没有活动的插件通道负责该路径。 |
405 | 空的 Allow: GET, POST 标头 | HEAD 或其他不受支持的方法；不会调用该组件。 |
| 429 | rate-limit JSON 或 webhook queue full | 按客户端的 webhook 上限，或路由的有界队列拒绝了接收请求。 |
| 502 | invalid webhook response | 组件响应超出了 4096 字节的限制。 |
| 503 | webhook 不可用 | 组件、宿主服务或下游通道接收方不可用。 |
| 504 | webhook 处理超时 | ååºæ—¶é—´é™åˆ¶ä¸º 10 秒，超时åŽå–消了解æžæˆ–投递。 |
网关在这个未认证的入口上，从不返回 guest、Wasmtime、secret、config 或下游错误的详细信息。这些详细信息会被限定大小，并附带插件归属信息记录到日志中。适用标准的 64 KiB 网关请求体上限。完成 guest 认证后，主机会在幂等性预留和投递之前，为 plugin.<alias> 应用实时的对等组。稳定的消息 ID 使用路由命名空间内、所有权安全的预留机制：正在处理中的重复请求会等待提交或回滚，而不会被提前确认。
发现表面
两个端点可以回答“我在这里能做什么?“这个问题:
OPTIONS /api/config返回 whole-config 类型的 JSON Schema。每个构建中保持静态；客户端应根据ETag标头进行缓存。其当前的Allow标头仍列出旧版PUT，但路由器并未注册它。OPTIONS /api/config/prop?path=<dotted>返回特定路径的 schema 片段，并带有Allow: GET, PUT, DELETE, OPTIONS。如果该路径在 schema 中不存在，则返回 404。
OPTIONS 返回功能能力。GET /api/config/prop 和 GET /api/config/list 返回用户的当前值。仪表板中的表单在加载时发起一次 OPTIONS 以获取类型和约束，然后通过 GET 填充字段，再通过 PUT/PATCH 写入。兼容性接口 GET /api/config 还会返回整个配置的快照，并对密钥进行掩码处理，从而使较旧的捆绑仪表板页面在面对较新的网关时不会失败。新客户端应优先使用按属性访问的接口，因为它携带字段元数据并对密钥进行显式处理。
CORS 预检请求（即携带 Access-Control-Request-Method 的请求）会获得标准的预检响应，并在返回 schema 主体之前提前结束。
GET /api/plugins 返回已通过认证的只读包目录，供仪表盘使用。它基于主机准入的已安装清单和已缓存的注册表生成每个包名对应的一行数据，采用与 plugin install 相同的未固定注册表选择规则。已安装记录与注册表记录保持分离，使客户端能够同时显示两者的版本，而无需推测是否存在可升级版本。该端点不执行注册表拉取，也不做任何修改操作。
该路由存在于所有网关构建版本中。当未启用 WASM 插件支持时，该路由返回 wasm_plugins_available: false 和空的包源，而不是 404。[plugins].enabled 表示的是配置意图，而非运行时健康状态。稳定的 issues 代码用于区分包源故障与有效的空目录，详细诊断信息仍保留在网关日志中。注册表下载 URL 和缓存的注册表 URL 永远不会被返回；可用记录仅暴露惰性的 name@version 安装标识。
Catalog 发现会在阻塞工作线程上运行，因为主机准入流程需要读取并校验已安装的 WASM 载荷。同一时间只允许运行一次扫描；并发请求会收到 503 Service Unavailable，且可以重试。该端点不会在请求之间缓存已准入的包状态。
属性级 CRUD
| 方法 | 路径 | 目的 |
|---|---|---|
GET | /api/config | 兼容性全配置快照（已遮盖机密）；新客户端应优先使用按属性提供的接口。 |
PATCH | /api/config | 原子化应用 JSON Patch (RFC 6902) 文档。 |
OPTIONS | /api/config | 整个配置的 JSON Schema（功能能力，而非具体值）。 |
GET | /api/config/prop?path=... | 读取单个字段。密钥仅返回 {path, populated}。 |
PUT | /api/config/prop | 写入一个字段。请求体：{path, value, comment?}。密钥仅返回 {path, populated: true}。 |
DELETE | /api/config/prop?path=... | 将单个字段重置为默认值。机密信息会返回 {path, populated: false}。 |
OPTIONS | /api/config/prop?path=... | 每个字段的架构片段。 |
GET | /api/config/list?prefix=... | 枚举每个可达路径及其类型和类别。密钥条目包含 {path, populated, is_secret: true}，但不含值。 |
POST | /api/config/init?section=... | 使用默认值实例化 None 嵌套节。动态映射别名不在此处创建；请使用 POST /api/config/map-key。 |
POST | /api/config/migrate | 就地应用磁盘上的架构迁移。等同于 zeroclaw config migrate。 |
原子批量写入：JSON Patch
PATCH /api/config 接受 JSON Patch 文档（RFC 6902）。支持的配置操作包括 add、replace、remove 和 test。ZeroClaw 还接受用于配置注释的 comment 扩展。配置操作在内存副本上执行；所有操作均应用完毕后，Config::validate() 对结果运行一次。若验证通过，新状态将被持久化并切换生效。若任何操作或最终验证失败，磁盘和内存中的状态均保持不变。注释标注在保存完成后以尽力而为的非致命方式应用。
move 和 copy 返回 400 op_not_supported，因为安全的引用图重写不属于此接口范畴。针对 #[secret] 路径的 test 操作会被拒绝并返回 secret_test_forbidden：差异化的结果将是客户端唯一能读取到的信号，而这会泄露该值。
路径语法：JSON 指针（/agents/researcher/model_provider）或点分形式（agents.researcher.model_provider）。两者均可接受；服务器会进行规范化处理。
命令行对应命令为 zeroclaw config patch <file-or-stdin>，它会对本地 Config 应用相同的操作集，并返回相同结构的响应格式（脚本可使用 --json）。
机密信息：通过 HTTP 进行只写操作
按属性读取绝不会暴露 secret 字段（即 schema 中标记为 #[secret] 或 #[derived_from_secret] 的字段）。它们的响应仅携带 {populated: bool}，不包含值、长度、掩码替身或哈希。而兼容性接口 GET /api/config 会在应用 MaskSecrets 后序列化整个配置，因此 secret 字段在此只能以掩码占位符的形式出现。这两种配置读取面都不会返回底层的 secret 值。
PUT 和 PATCH 写入新的密钥值并返回 {populated: true}；DELETE 清除该值并返回 {populated: false}。没有任何 HTTP 路径可以通过任何方式检索密钥。
稳定错误代码
错误以 JSON 格式返回，包含一个稳定的 code 字段以及一条便于阅读的 message。前端和脚本根据 code 进行匹配；UI 则根据路径进行匹配。
| 代码 | 状态 | 含义 |
|---|---|---|
path_not_found | 404 | 请求的属性在架构中不存在。 |
validation_failed | 400 | 整个配置的验证器拒绝了建议的状态。 |
dangling_reference | 400 | 配置的别名引用（例如 agents.<x>.model_provider）指向了一个不存在的目标（例如 providers.models.<type>.<alias>）。 |
value_type_mismatch | 400 | 提交的 JSON 值无法强制转换为目标类型。 |
op_not_supported | 400 | JSON Patch 操作为 move / copy / 未知操作。 |
secret_test_forbidden | 400 | JSON Patch test 操作针对了一个机密路径。 |
config_changed_externally | 409 | 磁盘上的配置与内存中的副本发生了偏移。（参见偏移检测。） |
reload_failed | 500 | 保存成功，但守护进程重新加载时无法读取新状态；磁盘上的内容已还原。 |
internal_error | 500 | 服务器端发生未分类的故障。 |
实时探索
网关运行后，可通过 http://<gateway-host>:<port>/api/docs 访问 Scalar API 浏览器。原始规范可在 /api/openapi.json 获取，供其他兼容的查看器使用。
浏览器的身份验证面板会绑定到规范中声明的 bearerAuth 方案，请在发起实时调用之前，将通过配对生成的 bearer 令牌粘贴到此处。该 URL 的 CLI 快捷命令是 zeroclaw config docs。
如果 Scalar 包无法从 CDN 加载（离线/隔离网络环境安装），页面会优雅降级，并将你指向位于 /api/openapi.json 的原始规范，以便你可以使用任何兼容的查看器（Insomnia、Postman、Swagger UI 等）。
事件流契约
GET /api/events 是一个原始的服务器发送事件（Server-Sent Events）流，包含可观测的运行时事件。它不是去重后每轮一行的生命周期时间线。
网关处理器、webhook 处理、cron/heartbeat 任务以及 agent-loop 观察者都可以将符合生命周期形态的事件发布到同一个广播路径中。客户端应将该流视为仅追加的观察日志。如果仪表板需要紧凑的回合时间线，应根据事件载荷中的标识符进行分组或去重，而不是假设每个 agent_start、llm_request 或 agent_end 帧只出现一次。
GET /api/events/history 从同一缓冲区中重放保留的最近事件，按从旧到新的顺序排列。它是为订阅者提供的重连窗口，而非独立的规范生命周期存储。