@gguf/claw 2026.2.1 → 2026.2.2

package/docs/zh-CN/gateway/openresponses-http-api.md

@@ -0,0 +1,319 @@
+---
+read_when:
+  - 集成使用 OpenResponses API 的客户端
+  - 你需要基于 item 的输入、客户端工具调用或 SSE 事件
+summary: 从 Gateway网关暴露一个兼容 OpenResponses 的 /v1/responses HTTP 端点
+title: OpenResponses API
+x-i18n:
+  generated_at: "2026-02-01T20:35:34Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 0597714837f8b210c38eeef53561894220c1473e54c56a5c69984847685d518c
+  source_path: gateway/openresponses-http-api.md
+  workflow: 14
+---
+
+# OpenResponses API (HTTP)
+
+OpenClaw 的 Gateway网关可以提供一个兼容 OpenResponses 的 `POST /v1/responses` 端点。
+
+此端点**默认禁用**。请先在配置中启用。
+
+- `POST /v1/responses`
+- 与 Gateway网关使用相同端口（WS + HTTP 多路复用）：`http://<gateway-host>:<port>/v1/responses`
+
+底层实现中，请求作为普通的 Gateway网关智能体运行来执行（与 `openclaw agent` 相同的代码路径），因此路由/权限/配置与你的 Gateway网关一致。
+
+## 认证
+
+使用 Gateway网关的认证配置。发送 bearer 令牌：
+
+- `Authorization: Bearer <token>`
+
+说明：
+
+- 当 `gateway.auth.mode="token"` 时，使用 `gateway.auth.token`（或 `OPENCLAW_GATEWAY_TOKEN`）。
+- 当 `gateway.auth.mode="password"` 时，使用 `gateway.auth.password`（或 `OPENCLAW_GATEWAY_PASSWORD`）。
+
+## 选择智能体
+
+无需自定义头：在 OpenResponses 的 `model` 字段中编码智能体 ID：
+
+- `model: "openclaw:<agentId>"`（示例：`"openclaw:main"`、`"openclaw:beta"`）
+- `model: "agent:<agentId>"`（别名）
+
+或通过头指定特定的 OpenClaw 智能体：
+
+- `x-openclaw-agent-id: <agentId>`（默认：`main`）
+
+高级用法：
+
+- `x-openclaw-session-key: <sessionKey>` 完全控制会话路由。
+
+## 启用端点
+
+将 `gateway.http.endpoints.responses.enabled` 设置为 `true`：
+
+```json5
+{
+  gateway: {
+    http: {
+      endpoints: {
+        responses: { enabled: true },
+      },
+    },
+  },
+}
+```
+
+## 禁用端点
+
+将 `gateway.http.endpoints.responses.enabled` 设置为 `false`：
+
+```json5
+{
+  gateway: {
+    http: {
+      endpoints: {
+        responses: { enabled: false },
+      },
+    },
+  },
+}
+```
+
+## 会话行为
+
+默认情况下，端点是**每次请求无状态的**（每次调用生成一个新的会话密钥）。
+
+如果请求包含 OpenResponses 的 `user` 字符串，Gateway网关会从中派生一个稳定的会话密钥，使重复调用可以共享同一个智能体会话。
+
+## 请求结构（已支持）
+
+请求遵循 OpenResponses API，使用基于 item 的输入。当前支持：
+
+- `input`：字符串或 item 对象数组。
+- `instructions`：合并到系统提示中。
+- `tools`：客户端工具定义（函数工具）。
+- `tool_choice`：过滤或要求客户端工具。
+- `stream`：启用 SSE 流式传输。
+- `max_output_tokens`：尽力而为的输出限制（取决于提供商）。
+- `user`：稳定的会话路由。
+
+已接受但**当前忽略**：
+
+- `max_tool_calls`
+- `reasoning`
+- `metadata`
+- `store`
+- `previous_response_id`
+- `truncation`
+
+## Items（输入）
+
+### `message`
+
+角色：`system`、`developer`、`user`、`assistant`。
+
+- `system` 和 `developer` 附加到系统提示中。
+- 最近的 `user` 或 `function_call_output` item 成为"当前消息"。
+- 更早的 user/assistant 消息作为历史上下文包含在内。
+
+### `function_call_output`（基于轮次的工具）
+
+将工具结果发送回模型：
+
+```json
+{
+  "type": "function_call_output",
+  "call_id": "call_123",
+  "output": "{\"temperature\": \"72F\"}"
+}
+```
+
+### `reasoning` 和 `item_reference`
+
+为兼容 schema 而接受，但在构建提示时忽略。
+
+## 工具（客户端函数工具）
+
+通过 `tools: [{ type: "function", function: { name, description?, parameters? } }]` 提供工具。
+
+如果智能体决定调用工具，响应会返回一个 `function_call` 输出 item。
+然后你发送一个包含 `function_call_output` 的后续请求以继续该轮次。
+
+## 图片（`input_image`）
+
+支持 base64 或 URL 来源：
+
+```json
+{
+  "type": "input_image",
+  "source": { "type": "url", "url": "https://example.com/image.png" }
+}
+```
+
+允许的 MIME 类型（当前）：`image/jpeg`、`image/png`、`image/gif`、`image/webp`。
+最大大小（当前）：10MB。
+
+## 文件（`input_file`）
+
+支持 base64 或 URL 来源：
+
+```json
+{
+  "type": "input_file",
+  "source": {
+    "type": "base64",
+    "media_type": "text/plain",
+    "data": "SGVsbG8gV29ybGQh",
+    "filename": "hello.txt"
+  }
+}
+```
+
+允许的 MIME 类型（当前）：`text/plain`、`text/markdown`、`text/html`、`text/csv`、
+`application/json`、`application/pdf`。
+
+最大大小（当前）：5MB。
+
+当前行为：
+
+- 文件内容被解码并添加到**系统提示**中，而非用户消息中，因此它是临时的（不会持久化到会话历史中）。
+- PDF 会被解析提取文本。如果发现的文本很少，前几页会被光栅化为图片并传递给模型。
+
+PDF 解析使用对 Node 友好的 `pdfjs-dist` 旧版构建（无 worker）。现代 PDF.js 构建需要浏览器 worker/DOM 全局对象，因此不在 Gateway网关中使用。
+
+URL 获取默认值：
+
+- `files.allowUrl`：`true`
+- `images.allowUrl`：`true`
+- 请求受到保护（DNS 解析、私有 IP 阻止、重定向上限、超时）。
+
+## 文件和图片限制（配置）
+
+默认值可在 `gateway.http.endpoints.responses` 下调整：
+
+```json5
+{
+  gateway: {
+    http: {
+      endpoints: {
+        responses: {
+          enabled: true,
+          maxBodyBytes: 20000000,
+          files: {
+            allowUrl: true,
+            allowedMimes: [
+              "text/plain",
+              "text/markdown",
+              "text/html",
+              "text/csv",
+              "application/json",
+              "application/pdf",
+            ],
+            maxBytes: 5242880,
+            maxChars: 200000,
+            maxRedirects: 3,
+            timeoutMs: 10000,
+            pdf: {
+              maxPages: 4,
+              maxPixels: 4000000,
+              minTextChars: 200,
+            },
+          },
+          images: {
+            allowUrl: true,
+            allowedMimes: ["image/jpeg", "image/png", "image/gif", "image/webp"],
+            maxBytes: 10485760,
+            maxRedirects: 3,
+            timeoutMs: 10000,
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+省略时的默认值：
+
+- `maxBodyBytes`：20MB
+- `files.maxBytes`：5MB
+- `files.maxChars`：200k
+- `files.maxRedirects`：3
+- `files.timeoutMs`：10s
+- `files.pdf.maxPages`：4
+- `files.pdf.maxPixels`：4,000,000
+- `files.pdf.minTextChars`：200
+- `images.maxBytes`：10MB
+- `images.maxRedirects`：3
+- `images.timeoutMs`：10s
+
+## 流式传输（SSE）
+
+设置 `stream: true` 以接收服务器发送事件（SSE）：
+
+- `Content-Type: text/event-stream`
+- 每个事件行为 `event: <type>` 和 `data: <json>`
+- 流以 `data: [DONE]` 结束
+
+当前发出的事件类型：
+
+- `response.created`
+- `response.in_progress`
+- `response.output_item.added`
+- `response.content_part.added`
+- `response.output_text.delta`
+- `response.output_text.done`
+- `response.content_part.done`
+- `response.output_item.done`
+- `response.completed`
+- `response.failed`（出错时）
+
+## 用量
+
+当底层提供商报告令牌计数时，`usage` 会被填充。
+
+## 错误
+
+错误使用如下 JSON 对象：
+
+```json
+{ "error": { "message": "...", "type": "invalid_request_error" } }
+```
+
+常见情况：
+
+- `401` 缺少/无效的认证
+- `400` 无效的请求体
+- `405` 错误的方法
+
+## 示例
+
+非流式：
+
+```bash
+curl -sS http://127.0.0.1:18789/v1/responses \
+  -H 'Authorization: Bearer YOUR_TOKEN' \
+  -H 'Content-Type: application/json' \
+  -H 'x-openclaw-agent-id: main' \
+  -d '{
+    "model": "openclaw",
+    "input": "hi"
+  }'
+```
+
+流式：
+
+```bash
+curl -N http://127.0.0.1:18789/v1/responses \
+  -H 'Authorization: Bearer YOUR_TOKEN' \
+  -H 'Content-Type: application/json' \
+  -H 'x-openclaw-agent-id: main' \
+  -d '{
+    "model": "openclaw",
+    "stream": true,
+    "input": "hi"
+  }'
+```

package/docs/zh-CN/gateway/pairing.md

@@ -0,0 +1,99 @@
+---
+read_when:
+  - 在没有 macOS UI 的情况下实现节点配对审批
+  - 添加用于审批远程节点的 CLI 流程
+  - 扩展 Gateway网关协议以支持节点管理
+summary: Gateway网关拥有的节点配对（方案 B），适用于 iOS 及其他远程节点
+title: Gateway网关拥有的配对
+x-i18n:
+  generated_at: "2026-02-01T20:35:26Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 1f5154292a75ea2c1470324babc99c6c46a5e4e16afb394ed323d28f6168f459
+  source_path: gateway/pairing.md
+  workflow: 14
+---
+
+# Gateway网关拥有的配对（方案 B）
+
+在 Gateway网关拥有的配对模式中，**Gateway网关** 是决定哪些节点允许加入的权威来源。UI（macOS 应用、未来的客户端）只是用于批准或拒绝待处理请求的前端。
+
+**重要说明：**WS 节点在 `connect` 过程中使用**设备配对**（角色 `node`）。`node.pair.*` 是一个独立的配对存储，**不会**控制 WS 握手。只有显式调用 `node.pair.*` 的客户端才使用此流程。
+
+## 概念
+
+- **待处理请求**：节点请求加入，需要审批。
+- **已配对节点**：已批准的节点，带有已签发的认证令牌。
+- **传输层**：Gateway网关 WS 端点转发请求但不决定成员资格。（旧版 TCP 桥接支持已弃用/移除。）
+
+## 配对工作原理
+
+1. 节点连接到 Gateway网关 WS 并请求配对。
+2. Gateway网关存储一个**待处理请求**并发出 `node.pair.requested` 事件。
+3. 你批准或拒绝该请求（通过 CLI 或 UI）。
+4. 批准后，Gateway网关签发一个**新令牌**（重新配对时令牌会轮换）。
+5. 节点使用该令牌重新连接，此时即为"已配对"状态。
+
+待处理请求会在 **5 分钟**后自动过期。
+
+## CLI 工作流（适合无界面环境）
+
+```bash
+openclaw nodes pending
+openclaw nodes approve <requestId>
+openclaw nodes reject <requestId>
+openclaw nodes status
+openclaw nodes rename --node <id|name|ip> --name "Living Room iPad"
+```
+
+`nodes status` 显示已配对/已连接的节点及其能力。
+
+## API 接口（Gateway网关协议）
+
+事件：
+
+- `node.pair.requested` — 创建新的待处理请求时发出。
+- `node.pair.resolved` — 请求被批准/拒绝/过期时发出。
+
+方法：
+
+- `node.pair.request` — 创建或复用待处理请求。
+- `node.pair.list` — 列出待处理和已配对的节点。
+- `node.pair.approve` — 批准待处理请求（签发令牌）。
+- `node.pair.reject` — 拒绝待处理请求。
+- `node.pair.verify` — 验证 `{ nodeId, token }`。
+
+注意事项：
+
+- `node.pair.request` 对每个节点是幂等的：重复调用返回相同的待处理请求。
+- 批准操作**始终**生成新令牌；`node.pair.request` 不会返回任何令牌。
+- 请求可包含 `silent: true` 作为自动批准流程的提示。
+
+## 自动批准（macOS 应用）
+
+macOS 应用可在以下条件满足时选择性地尝试**静默批准**：
+
+- 请求标记为 `silent`，且
+- 应用能够使用同一用户验证与 Gateway网关主机的 SSH 连接。
+
+如果静默批准失败，则回退到常规的"批准/拒绝"提示。
+
+## 存储（本地，私有）
+
+配对状态存储在 Gateway网关状态目录下（默认 `~/.openclaw`）：
+
+- `~/.openclaw/nodes/paired.json`
+- `~/.openclaw/nodes/pending.json`
+
+如果你覆盖了 `OPENCLAW_STATE_DIR`，`nodes/` 文件夹会随之移动。
+
+安全注意事项：
+
+- 令牌是机密信息；请将 `paired.json` 视为敏感文件。
+- 轮换令牌需要重新审批（或删除节点条目）。
+
+## 传输层行为
+
+- 传输层是**无状态的**；它不存储成员信息。
+- 如果 Gateway网关离线或配对功能被禁用，节点无法配对。
+- 如果 Gateway网关处于远程模式，配对仍然基于远程 Gateway网关的存储进行。

package/docs/zh-CN/gateway/protocol.md

@@ -0,0 +1,211 @@
+---
+read_when:
+  - 实现或更新 Gateway网关 WebSocket 客户端
+  - 调试协议不匹配或连接失败问题
+  - 重新生成协议 schema/模型
+summary: Gateway网关 WebSocket 协议：握手、帧、版本控制
+title: Gateway网关协议
+x-i18n:
+  generated_at: "2026-02-01T20:35:39Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: bdafac40d53565901b2df450617287664d77fe4ff52681fa00cab9046b2fd850
+  source_path: gateway/protocol.md
+  workflow: 14
+---
+
+# Gateway网关协议 (WebSocket)
+
+Gateway网关 WebSocket 协议是 OpenClaw 的**统一控制平面 + 节点传输层**。所有客户端（CLI、Web UI、macOS 应用、iOS/Android 节点、无头节点）均通过 WebSocket 连接，并在握手时声明其**角色** + **作用域**。
+
+## 传输
+
+- WebSocket，文本帧携带 JSON 负载。
+- 第一帧**必须**是 `connect` 请求。
+
+## 握手 (connect)
+
+Gateway网关 → 客户端（连接前挑战）：
+
+```json
+{
+  "type": "event",
+  "event": "connect.challenge",
+  "payload": { "nonce": "…", "ts": 1737264000000 }
+}
+```
+
+客户端 → Gateway网关：
+
+```json
+{
+  "type": "req",
+  "id": "…",
+  "method": "connect",
+  "params": {
+    "minProtocol": 3,
+    "maxProtocol": 3,
+    "client": {
+      "id": "cli",
+      "version": "1.2.3",
+      "platform": "macos",
+      "mode": "operator"
+    },
+    "role": "operator",
+    "scopes": ["operator.read", "operator.write"],
+    "caps": [],
+    "commands": [],
+    "permissions": {},
+    "auth": { "token": "…" },
+    "locale": "en-US",
+    "userAgent": "openclaw-cli/1.2.3",
+    "device": {
+      "id": "device_fingerprint",
+      "publicKey": "…",
+      "signature": "…",
+      "signedAt": 1737264000000,
+      "nonce": "…"
+    }
+  }
+}
+```
+
+Gateway网关 → 客户端：
+
+```json
+{
+  "type": "res",
+  "id": "…",
+  "ok": true,
+  "payload": { "type": "hello-ok", "protocol": 3, "policy": { "tickIntervalMs": 15000 } }
+}
+```
+
+当签发设备令牌时，`hello-ok` 还包含：
+
+```json
+{
+  "auth": {
+    "deviceToken": "…",
+    "role": "operator",
+    "scopes": ["operator.read", "operator.write"]
+  }
+}
+```
+
+### 节点示例
+
+```json
+{
+  "type": "req",
+  "id": "…",
+  "method": "connect",
+  "params": {
+    "minProtocol": 3,
+    "maxProtocol": 3,
+    "client": {
+      "id": "ios-node",
+      "version": "1.2.3",
+      "platform": "ios",
+      "mode": "node"
+    },
+    "role": "node",
+    "scopes": [],
+    "caps": ["camera", "canvas", "screen", "location", "voice"],
+    "commands": ["camera.snap", "canvas.navigate", "screen.record", "location.get"],
+    "permissions": { "camera.capture": true, "screen.record": false },
+    "auth": { "token": "…" },
+    "locale": "en-US",
+    "userAgent": "openclaw-ios/1.2.3",
+    "device": {
+      "id": "device_fingerprint",
+      "publicKey": "…",
+      "signature": "…",
+      "signedAt": 1737264000000,
+      "nonce": "…"
+    }
+  }
+}
+```
+
+## 帧格式
+
+- **请求**：`{type:"req", id, method, params}`
+- **响应**：`{type:"res", id, ok, payload|error}`
+- **事件**：`{type:"event", event, payload, seq?, stateVersion?}`
+
+具有副作用的方法需要**幂等键**（参见 schema）。
+
+## 角色 + 作用域
+
+### 角色
+
+- `operator` = 控制平面客户端（CLI/UI/自动化）。
+- `node` = 能力宿主（摄像头/屏幕/画布/system.run）。
+
+### 作用域 (operator)
+
+常用作用域：
+
+- `operator.read`
+- `operator.write`
+- `operator.admin`
+- `operator.approvals`
+- `operator.pairing`
+
+### 能力/命令/权限 (node)
+
+节点在连接时声明能力：
+
+- `caps`：高级能力类别。
+- `commands`：允许调用的命令白名单。
+- `permissions`：细粒度开关（例如 `screen.record`、`camera.capture`）。
+
+Gateway网关将这些视为**声明**，并在服务端执行白名单校验。
+
+## 在线状态
+
+- `system-presence` 返回以设备身份为键的条目。
+- 在线状态条目包含 `deviceId`、`roles` 和 `scopes`，这样 UI 可以为每个设备显示一行，即使该设备同时以 **operator** 和 **node** 身份连接。
+
+### 节点辅助方法
+
+- 节点可以调用 `skills.bins` 获取当前 Skills 可执行文件列表，用于自动允许检查。
+
+## 执行审批
+
+- 当执行请求需要审批时，Gateway网关会广播 `exec.approval.requested`。
+- Operator 客户端通过调用 `exec.approval.resolve` 进行处理（需要 `operator.approvals` 作用域）。
+
+## 版本控制
+
+- `PROTOCOL_VERSION` 定义在 `src/gateway/protocol/schema.ts` 中。
+- 客户端发送 `minProtocol` + `maxProtocol`；服务端在不匹配时拒绝连接。
+- Schema 和模型从 TypeBox 定义生成：
+  - `pnpm protocol:gen`
+  - `pnpm protocol:gen:swift`
+  - `pnpm protocol:check`
+
+## 认证
+
+- 如果设置了 `OPENCLAW_GATEWAY_TOKEN`（或 `--token`），`connect.params.auth.token` 必须匹配，否则连接将被关闭。
+- 配对完成后，Gateway网关会签发一个**设备令牌**，其作用域限定为连接的角色 + 作用域。该令牌在 `hello-ok.auth.deviceToken` 中返回，客户端应持久化保存以供后续连接使用。
+- 设备令牌可通过 `device.token.rotate` 和 `device.token.revoke` 进行轮换/撤销（需要 `operator.pairing` 作用域）。
+
+## 设备身份 + 配对
+
+- 节点应包含一个稳定的设备身份（`device.id`），由密钥对指纹派生。
+- Gateway网关按设备 + 角色签发令牌。
+- 新设备 ID 需要配对审批，除非启用了本地自动审批。
+- **本地**连接包括 local loopback 和 Gateway网关主机自身的 tailnet 地址（因此同一主机的 tailnet 绑定仍可自动审批）。
+- 所有 WebSocket 客户端在 `connect` 时必须包含 `device` 身份（operator + node）。控制 UI 仅在启用 `gateway.controlUi.allowInsecureAuth` 时可以省略（或使用 `gateway.controlUi.dangerouslyDisableDeviceAuth` 作为紧急措施）。
+- 非本地连接必须对服务端提供的 `connect.challenge` nonce 进行签名。
+
+## TLS + 证书固定
+
+- WebSocket 连接支持 TLS。
+- 客户端可选择固定 Gateway网关证书指纹（参见 `gateway.tls` 配置以及 `gateway.remote.tlsFingerprint` 或 CLI `--tls-fingerprint`）。
+
+## 范围
+
+此协议暴露了**完整的 Gateway网关 API**（状态、渠道、模型、聊天、智能体、会话、节点、审批等）。确切的 API 接口由 `src/gateway/protocol/schema.ts` 中的 TypeBox schema 定义。