@quantumclaw/quantumclaw 2026.3.22

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

@@ -0,0 +1,124 @@
+---
+read_when:
+  - 在 localhost 之外暴露 Gateway 网关控制 UI
+  - 自动化 tailnet 或公共仪表盘访问
+summary: 为 Gateway 网关仪表盘集成 Tailscale Serve/Funnel
+title: Tailscale
+x-i18n:
+  generated_at: "2026-02-03T07:49:04Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: c900c70a9301f2909a3a29a6fb0e6edfc8c18dba443f2e71b9cfadbc58167911
+  source_path: gateway/tailscale.md
+  workflow: 15
+---
+
+# Tailscale（Gateway 网关仪表盘）
+
+QuantumClaw 可以为 Gateway 网关仪表盘和 WebSocket 端口自动配置 Tailscale **Serve**（tailnet）或 **Funnel**（公共）。这使 Gateway 网关保持绑定到 loopback，同时 Tailscale 提供 HTTPS、路由和（对于 Serve）身份头。
+
+## 模式
+
+- `serve`：仅限 Tailnet 的 Serve，通过 `tailscale serve`。Gateway 网关保持在 `127.0.0.1` 上。
+- `funnel`：通过 `tailscale funnel` 的公共 HTTPS。QuantumClaw 需要共享密码。
+- `off`：默认（无 Tailscale 自动化）。
+
+## 认证
+
+设置 `gateway.auth.mode` 来控制握手：
+
+- `token`（设置 `QUANTUMCLAW_GATEWAY_TOKEN` 时的默认值）
+- `password`（通过 `QUANTUMCLAW_GATEWAY_PASSWORD` 或配置的共享密钥）
+
+当 `tailscale.mode = "serve"` 且 `gateway.auth.allowTailscale` 为 `true` 时，
+有效的 Serve 代理请求可以通过 Tailscale 身份头（`tailscale-user-login`）进行认证，无需提供令牌/密码。QuantumClaw 通过本地 Tailscale 守护进程（`tailscale whois`）解析 `x-forwarded-for` 地址并将其与头匹配来验证身份，然后才接受它。
+QuantumClaw 仅在请求从 loopback 到达并带有 Tailscale 的 `x-forwarded-for`、`x-forwarded-proto` 和 `x-forwarded-host` 头时才将其视为 Serve 请求。
+要要求显式凭证，设置 `gateway.auth.allowTailscale: false` 或强制 `gateway.auth.mode: "password"`。
+
+## 配置示例
+
+### 仅限 Tailnet（Serve）
+
+```json5
+{
+  gateway: {
+    bind: "loopback",
+    tailscale: { mode: "serve" },
+  },
+}
+```
+
+打开：`https://<magicdns>/`（或你配置的 `gateway.controlUi.basePath`）
+
+### 仅限 Tailnet（绑定到 Tailnet IP）
+
+当你希望 Gateway 网关直接监听 Tailnet IP 时使用此方式（无 Serve/Funnel）。
+
+```json5
+{
+  gateway: {
+    bind: "tailnet",
+    auth: { mode: "token", token: "your-token" },
+  },
+}
+```
+
+从另一个 Tailnet 设备连接：
+
+- 控制 UI：`http://<tailscale-ip>:18789/`
+- WebSocket：`ws://<tailscale-ip>:18789`
+
+注意：在此模式下 loopback（`http://127.0.0.1:18789`）将**不**工作。
+
+### 公共互联网（Funnel + 共享密码）
+
+```json5
+{
+  gateway: {
+    bind: "loopback",
+    tailscale: { mode: "funnel" },
+    auth: { mode: "password", password: "replace-me" },
+  },
+}
+```
+
+优先使用 `QUANTUMCLAW_GATEWAY_PASSWORD` 而不是将密码提交到磁盘。
+
+## CLI 示例
+
+```bash
+quantumclaw gateway --tailscale serve
+quantumclaw gateway --tailscale funnel --auth password
+```
+
+## 注意事项
+
+- Tailscale Serve/Funnel 需要安装并登录 `tailscale` CLI。
+- `tailscale.mode: "funnel"` 除非认证模式为 `password`，否则拒绝启动，以避免公共暴露。
+- 如果你希望 QuantumClaw 在关闭时撤销 `tailscale serve` 或 `tailscale funnel` 配置，设置 `gateway.tailscale.resetOnExit`。
+- `gateway.bind: "tailnet"` 是直接 Tailnet 绑定（无 HTTPS，无 Serve/Funnel）。
+- `gateway.bind: "auto"` 优先 loopback；如果你想要仅 Tailnet，使用 `tailnet`。
+- Serve/Funnel 仅暴露 **Gateway 网关控制 UI + WS**。节点通过相同的 Gateway 网关 WS 端点连接，因此 Serve 可以用于节点访问。
+
+## 浏览器控制（远程 Gateway 网关 + 本地浏览器）
+
+如果你在一台机器上运行 Gateway 网关但想在另一台机器上驱动浏览器，
+在浏览器机器上运行一个**节点主机**并让两者保持在同一个 tailnet 上。
+Gateway 网关会将浏览器操作代理到节点；不需要单独的控制服务器或 Serve URL。
+
+避免将 Funnel 用于浏览器控制；将节点配对视为操作者访问。
+
+## Tailscale 前提条件 + 限制
+
+- Serve 需要为你的 tailnet 启用 HTTPS；如果缺少，CLI 会提示。
+- Serve 注入 Tailscale 身份头；Funnel 不会。
+- Funnel 需要 Tailscale v1.38.3+、MagicDNS、启用 HTTPS 和 funnel 节点属性。
+- Funnel 仅支持通过 TLS 的端口 `443`、`8443` 和 `10000`。
+- macOS 上的 Funnel 需要开源 Tailscale 应用变体。
+
+## 了解更多
+
+- Tailscale Serve 概述：https://tailscale.com/kb/1312/serve
+- `tailscale serve` 命令：https://tailscale.com/kb/1242/tailscale-serve
+- Tailscale Funnel 概述：https://tailscale.com/kb/1223/tailscale-funnel
+- `tailscale funnel` 命令：https://tailscale.com/kb/1311/tailscale-funnel

package/docs/zh-CN/gateway/tools-invoke-http-api.md

@@ -0,0 +1,92 @@
+---
+read_when:
+  - 不运行完整智能体回合直接调用工具
+  - 构建需要工具策略强制执行的自动化
+summary: 通过 Gateway 网关 HTTP 端点直接调用单个工具
+title: 工具调用 API
+x-i18n:
+  generated_at: "2026-02-03T07:48:58Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 17ccfbe0b0d9bb61cc46fb21f5c09b106ba6e8e4c2c14135a11ca8d5b77b8a88
+  source_path: gateway/tools-invoke-http-api.md
+  workflow: 15
+---
+
+# 工具调用（HTTP）
+
+QuantumClaw 的 Gateway 网关暴露了一个简单的 HTTP 端点用于直接调用单个工具。它始终启用，但受 Gateway 网关认证和工具策略限制。
+
+- `POST /tools/invoke`
+- 与 Gateway 网关相同的端口（WS + HTTP 多路复用）：`http://<gateway-host>:<port>/tools/invoke`
+
+默认最大负载大小为 2 MB。
+
+## 认证
+
+使用 Gateway 网关认证配置。发送 bearer 令牌：
+
+- `Authorization: Bearer <token>`
+
+说明：
+
+- 当 `gateway.auth.mode="token"` 时，使用 `gateway.auth.token`（或 `QUANTUMCLAW_GATEWAY_TOKEN`）。
+- 当 `gateway.auth.mode="password"` 时，使用 `gateway.auth.password`（或 `QUANTUMCLAW_GATEWAY_PASSWORD`）。
+
+## 请求体
+
+```json
+{
+  "tool": "sessions_list",
+  "action": "json",
+  "args": {},
+  "sessionKey": "main",
+  "dryRun": false
+}
+```
+
+字段：
+
+- `tool`（string，必需）：要调用的工具名称。
+- `action`（string，可选）：如果工具 schema 支持 `action` 且 args 负载省略了它，则映射到 args。
+- `args`（object，可选）：工具特定的参数。
+- `sessionKey`（string，可选）：目标会话键。如果省略或为 `"main"`，Gateway 网关使用配置的主会话键（遵循 `session.mainKey` 和默认智能体，或在全局范围中使用 `global`）。
+- `dryRun`（boolean，可选）：保留供将来使用；当前忽略。
+
+## 策略 + 路由行为
+
+工具可用性通过 Gateway 网关智能体使用的相同策略链过滤：
+
+- `tools.profile` / `tools.byProvider.profile`
+- `tools.allow` / `tools.byProvider.allow`
+- `agents.<id>.tools.allow` / `agents.<id>.tools.byProvider.allow`
+- 群组策略（如果会话键映射到群组或渠道）
+- 子智能体策略（使用子智能体会话键调用时）
+
+如果工具不被策略允许，端点返回 **404**。
+
+为帮助群组策略解析上下文，你可以选择设置：
+
+- `x-quantumclaw-message-channel: <channel>`（示例：`slack`、`telegram`）
+- `x-quantumclaw-account-id: <accountId>`（当存在多个账户时）
+
+## 响应
+
+- `200` → `{ ok: true, result }`
+- `400` → `{ ok: false, error: { type, message } }`（无效请求或工具错误）
+- `401` → 未授权
+- `404` → 工具不可用（未找到或未在允许列表中）
+- `405` → 方法不允许
+
+## 示例
+
+```bash
+curl -sS http://127.0.0.1:18789/tools/invoke \
+  -H 'Authorization: Bearer YOUR_TOKEN' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "tool": "sessions_list",
+    "action": "json",
+    "args": {}
+  }'
+```