@gguf/claw 2026.2.1 → 2026.2.2

package/docs/zh-CN/render.mdx

@@ -0,0 +1,169 @@
+---
+title: 在 Render 上部署
+x-i18n:
+  generated_at: "2026-02-01T21:38:27Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 03f0f277145daf6012ce33a9e8447d2eaaf346dfdb0df57a61ebf90b18b67c65
+  source_path: render.mdx
+  workflow: 15
+---
+
+使用基础设施即代码方式在 Render 上部署 OpenClaw。内置的 `render.yaml` Blueprint 以声明式方式定义了你的整个技术栈——服务、磁盘、环境变量，让你只需一键即可完成部署，并将基础设施与代码一同进行版本管理。
+
+## 前提条件
+
+- 一个 [Render 账户](https://render.com)（提供免费套餐）
+- 来自你首选[模型提供商](/providers)的 API 密钥
+
+## 使用 Render Blueprint 部署
+
+<a
+  href="https://render.com/deploy?repo=https://github.com/openclaw/openclaw"
+  target="_blank"
+  rel="noreferrer"
+>
+  部署到 Render
+</a>
+
+点击此链接将会：
+
+1. 根据本仓库根目录下的 `render.yaml` Blueprint 创建一个新的 Render 服务。
+2. 提示你设置 `SETUP_PASSWORD`
+3. 构建 Docker 镜像并部署
+
+部署完成后，你的服务 URL 格式为 `https://<service-name>.onrender.com`。
+
+## 了解 Blueprint
+
+Render Blueprint 是定义基础设施的 YAML 文件。本仓库中的 `render.yaml` 配置了运行 OpenClaw 所需的一切：
+
+```yaml
+services:
+  - type: web
+    name: openclaw
+    runtime: docker
+    plan: starter
+    healthCheckPath: /health
+    envVars:
+      - key: PORT
+        value: "8080"
+      - key: SETUP_PASSWORD
+        sync: false # prompts during deploy
+      - key: OPENCLAW_STATE_DIR
+        value: /data/.openclaw
+      - key: OPENCLAW_WORKSPACE_DIR
+        value: /data/workspace
+      - key: OPENCLAW_GATEWAY_TOKEN
+        generateValue: true # auto-generates a secure token
+    disk:
+      name: openclaw-data
+      mountPath: /data
+      sizeGB: 1
+```
+
+使用的关键 Blueprint 功能：
+
+| 功能                  | 用途                                     |
+| --------------------- | ---------------------------------------- |
+| `runtime: docker`     | 从仓库的 Dockerfile 进行构建             |
+| `healthCheckPath`     | Render 监控 `/health` 并重启不健康的实例 |
+| `sync: false`         | 在部署时提示输入值（用于密钥）           |
+| `generateValue: true` | 自动生成加密安全的值                     |
+| `disk`                | 持久化存储，在重新部署后数据仍然保留     |
+
+## 选择套餐
+
+| 套餐      | 休眠机制           | 磁盘   | 适用场景         |
+| --------- | ------------------ | ------ | ---------------- |
+| Free      | 空闲 15 分钟后休眠 | 不可用 | 测试、演示       |
+| Starter   | 永不休眠           | 1GB+   | 个人使用、小团队 |
+| Standard+ | 永不休眠           | 1GB+   | 生产环境、多渠道 |
+
+Blueprint 默认使用 `starter`。如需使用免费套餐，请在你 fork 的 `render.yaml` 中将 `plan: free`（但请注意：没有持久化磁盘意味着每次部署后配置都会重置）。
+
+## 部署完成后
+
+### 完成设置向导
+
+1. 访问 `https://<your-service>.onrender.com/setup`
+2. 输入你的 `SETUP_PASSWORD`
+3. 选择模型提供商并粘贴你的 API 密钥
+4. 可选配置消息渠道（Telegram、Discord、Slack）
+5. 点击 **Run setup**
+
+### 访问控制面板
+
+Web 管理面板位于 `https://<your-service>.onrender.com/openclaw`。
+
+## Render 仪表盘功能
+
+### 日志
+
+在 **Dashboard → 你的服务 → Logs** 中查看实时日志。可按以下类型筛选：
+
+- 构建日志（Docker 镜像创建）
+- 部署日志（服务启动）
+- 运行时日志（应用输出）
+
+### Shell 访问
+
+如需调试，可通过 **Dashboard → 你的服务 → Shell** 打开 shell 会话。持久化磁盘挂载在 `/data`。
+
+### 环境变量
+
+在 **Dashboard → 你的服务 → Environment** 中修改变量。更改会触发自动重新部署。
+
+### 自动部署
+
+如果你使用的是原始 OpenClaw 仓库，Render 不会自动部署你的 OpenClaw。要更新它，请在仪表盘中手动执行 Blueprint 同步。
+
+## 自定义域名
+
+1. 前往 **Dashboard → 你的服务 → Settings → Custom Domains**
+2. 添加你的域名
+3. 按照指引配置 DNS（CNAME 指向 `*.onrender.com`）
+4. Render 会自动配置 TLS 证书
+
+## 扩展
+
+Render 支持水平和垂直扩展：
+
+- **垂直扩展**：更改套餐以获取更多 CPU/内存
+- **水平扩展**：增加实例数量（Standard 套餐及以上）
+
+对于 OpenClaw，垂直扩展通常就足够了。水平扩展需要粘性会话或外部状态管理。
+
+## 备份与迁移
+
+随时导出你的配置和工作区：
+
+```
+https://<your-service>.onrender.com/setup/export
+```
+
+这将下载一个可移植的备份文件，你可以在任何 OpenClaw 主机上恢复。
+
+## 故障排除
+
+### 服务无法启动
+
+在 Render 仪表盘中检查部署日志。常见问题：
+
+- 缺少 `SETUP_PASSWORD` — Blueprint 会提示输入此值，但请确认已设置
+- 端口不匹配 — 确保 `PORT=8080` 与 Dockerfile 暴露的端口一致
+
+### 冷启动缓慢（免费套餐）
+
+免费套餐的服务在 15 分钟无活动后会休眠。休眠后的首次请求需要几秒钟等待容器启动。升级到 Starter 套餐可实现始终在线。
+
+### 重新部署后数据丢失
+
+这发生在免费套餐上（无持久化磁盘）。升级到付费套餐，或通过 `/setup/export` 定期导出你的配置。
+
+### 健康检查失败
+
+Render 期望在 30 秒内从 `/health` 获得 200 响应。如果构建成功但部署失败，可能是服务启动耗时过长。请检查：
+
+- 构建日志中是否有错误
+- 容器是否能通过 `docker build && docker run` 在本地正常运行

package/docs/zh-CN/scripts.md

@@ -0,0 +1,40 @@
+---
+read_when:
+  - 从仓库运行脚本时
+  - 在 ./scripts 下添加或修改脚本时
+summary: 仓库脚本：用途、范围和安全注意事项
+title: 脚本
+x-i18n:
+  generated_at: "2026-02-01T21:38:11Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: bfedc3c123c4a43b351f793e2137568786f90732723da5fd223c2a088bc59e43
+  source_path: scripts.md
+  workflow: 15
+---
+
+# 脚本
+
+`scripts/` 目录包含用于本地工作流和运维任务的辅助脚本。
+当任务明确与某个脚本相关时使用这些脚本；否则优先使用 CLI。
+
+## 约定
+
+- 除非在文档或发布检查清单中引用，否则脚本为**可选**。
+- 当 CLI 接口存在时优先使用（例如：认证监控使用 `openclaw models status --check`）。
+- 假定脚本与特定主机相关；在新机器上运行前请先阅读脚本内容。
+
+## Git 钩子
+
+- `scripts/setup-git-hooks.js`：在 git 仓库中尽力设置 `core.hooksPath`。
+- `scripts/format-staged.js`：用于暂存的 `src/` 和 `test/` 文件的预提交格式化工具。
+
+## 认证监控脚本
+
+认证监控脚本的文档请参阅：
+[/automation/auth-monitoring](/automation/auth-monitoring)
+
+## 添加脚本时
+
+- 保持脚本专注且有文档说明。
+- 在相关文档中添加简短条目（如果缺少则创建一个）。

package/docs/zh-CN/security/formal-verification.md

@@ -0,0 +1,169 @@
+---
+permalink: /security/formal-verification/
+summary: OpenClaw 最高风险路径的机器验证安全模型。
+title: 形式化验证（安全模型）
+x-i18n:
+  generated_at: "2026-02-01T21:38:31Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 8dff6ea41a37fb6b870424e4e788015c3f8a6099075eece5dbf909883c045106
+  source_path: security/formal-verification.md
+  workflow: 15
+---
+
+# 形式化验证（安全模型）
+
+本页面跟踪 OpenClaw 的**形式化安全模型**（目前使用 TLA+/TLC；后续按需扩展）。
+
+> 注意：一些较旧的链接可能引用的是之前的项目名称。
+
+**目标（北极星）：** 提供机器验证的论证，证明 OpenClaw 在明确假设下执行了其预期的安全策略（授权、会话隔离、工具门控和错误配置安全性）。
+
+**当前状态：** 一个可执行的、以攻击者为驱动的**安全回归测试套件**：
+
+- 每个声明都有一个在有限状态空间上运行的模型检查。
+- 许多声明都有一个配对的**负面模型**，为现实的漏洞类别生成反例追踪。
+
+**尚未实现的：** 证明"OpenClaw 在所有方面都是安全的"或完整的 TypeScript 实现是正确的。
+
+## 模型存放位置
+
+模型维护在一个独立的仓库中：[vignesh07/openclaw-formal-models](https://github.com/vignesh07/openclaw-formal-models)。
+
+## 重要注意事项
+
+- 这些是**模型**，而非完整的 TypeScript 实现。模型与代码之间可能存在偏差。
+- 结果受限于 TLC 探索的状态空间；"绿色"并不意味着超出建模假设和边界之外的安全性。
+- 一些声明依赖于明确的环境假设（例如，正确的部署、正确的配置输入）。
+
+## 复现结果
+
+目前，通过在本地克隆模型仓库并运行 TLC 来复现结果（见下文）。未来的迭代可能提供：
+
+- 带有公开产物（反例追踪、运行日志）的 CI 运行模型
+- 用于小规模有界检查的托管"运行此模型"工作流
+
+开始使用：
+
+```bash
+git clone https://github.com/vignesh07/openclaw-formal-models
+cd openclaw-formal-models
+
+# Java 11+ required (TLC runs on the JVM).
+# The repo vendors a pinned `tla2tools.jar` (TLA+ tools) and provides `bin/tlc` + Make targets.
+
+make <target>
+```
+
+### Gateway网关暴露与开放 Gateway网关错误配置
+
+**声明：** 在没有认证的情况下绑定到非本地 local loopback 可能导致远程入侵/增加暴露面；令牌/密码可以阻止未经授权的攻击者（在模型假设下）。
+
+- 绿色运行：
+  - `make gateway-exposure-v2`
+  - `make gateway-exposure-v2-protected`
+- 红色（预期）：
+  - `make gateway-exposure-v2-negative`
+
+另见：模型仓库中的 `docs/gateway-exposure-matrix.md`。
+
+### Nodes.run 管道（最高风险能力）
+
+**声明：** `nodes.run` 需要 (a) 节点命令允许列表加上已声明的命令，以及 (b) 配置后的实时审批；审批使用令牌化以防止重放（在模型中）。
+
+- 绿色运行：
+  - `make nodes-pipeline`
+  - `make approvals-token`
+- 红色（预期）：
+  - `make nodes-pipeline-negative`
+  - `make approvals-token-negative`
+
+### 配对存储（私信门控）
+
+**声明：** 配对请求遵守 TTL 和待处理请求上限。
+
+- 绿色运行：
+  - `make pairing`
+  - `make pairing-cap`
+- 红色（预期）：
+  - `make pairing-negative`
+  - `make pairing-cap-negative`
+
+### 入口门控（提及 + 控制命令绕过）
+
+**声明：** 在需要提及的群组上下文中，未经授权的"控制命令"无法绕过提及门控。
+
+- 绿色：
+  - `make ingress-gating`
+- 红色（预期）：
+  - `make ingress-gating-negative`
+
+### 路由/会话密钥隔离
+
+**声明：** 来自不同对等方的私信不会合并到同一个会话中，除非明确链接/配置。
+
+- 绿色：
+  - `make routing-isolation`
+- 红色（预期）：
+  - `make routing-isolation-negative`
+
+## v1++：额外的有界模型（并发、重试、追踪正确性）
+
+这些是后续模型，围绕真实世界的故障模式（非原子更新、重试和消息扇出）提高保真度。
+
+### 配对存储并发/幂等性
+
+**声明：** 配对存储应在交错执行下也能执行 `MaxPending` 和幂等性（即"检查后写入"必须是原子的/加锁的；刷新不应创建重复项）。
+
+含义：
+
+- 在并发请求下，不能超过渠道的 `MaxPending` 限制。
+- 对同一 `(channel, sender)` 的重复请求/刷新不应创建重复的活跃待处理行。
+
+- 绿色运行：
+  - `make pairing-race`（原子/加锁的上限检查）
+  - `make pairing-idempotency`
+  - `make pairing-refresh`
+  - `make pairing-refresh-race`
+- 红色（预期）：
+  - `make pairing-race-negative`（非原子的 begin/commit 上限竞争）
+  - `make pairing-idempotency-negative`
+  - `make pairing-refresh-negative`
+  - `make pairing-refresh-race-negative`
+
+### 入口追踪关联/幂等性
+
+**声明：** 摄入应在扇出过程中保持追踪关联，并在提供商重试下保持幂等性。
+
+含义：
+
+- 当一个外部事件变成多个内部消息时，每个部分都保持相同的追踪/事件标识。
+- 重试不会导致重复处理。
+- 如果缺少提供商事件 ID，去重将回退到安全的键（例如追踪 ID），以避免丢弃不同的事件。
+
+- 绿色：
+  - `make ingress-trace`
+  - `make ingress-trace2`
+  - `make ingress-idempotency`
+  - `make ingress-dedupe-fallback`
+- 红色（预期）：
+  - `make ingress-trace-negative`
+  - `make ingress-trace2-negative`
+  - `make ingress-idempotency-negative`
+  - `make ingress-dedupe-fallback-negative`
+
+### 路由 dmScope 优先级 + identityLinks
+
+**声明：** 路由必须默认保持私信会话隔离，仅在明确配置时才合并会话（渠道优先级 + 身份链接）。
+
+含义：
+
+- 渠道特定的 dmScope 覆盖必须优先于全局默认值。
+- identityLinks 应仅在明确链接的组内合并，而不是跨不相关的对等方。
+
+- 绿色：
+  - `make routing-precedence`
+  - `make routing-identitylinks`
+- 红色（预期）：
+  - `make routing-precedence-negative`
+  - `make routing-identitylinks-negative`

package/docs/zh-CN/start/getting-started.md

@@ -0,0 +1,210 @@
+---
+read_when:
+  - 从零开始的首次设置
+  - 你希望找到从安装 → 新手引导 → 发送第一条消息的最快路径
+summary: 入门指南：从零开始到发送第一条消息（向导、认证、渠道、配对）
+title: 入门指南
+x-i18n:
+  generated_at: "2026-02-01T13:38:44Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: d0ebc83c10efc569eaf6fb32368a29ef75a373f15da61f3499621462f08aff63
+  source_path: start/getting-started.md
+  workflow: 9
+---
+
+# 入门指南
+
+目标：从 **零开始** → **第一次成功聊天** （使用合理的默认配置）尽可能快地完成。
+
+最快聊天方式：打开控制界面（无需设置渠道）。运行 `openclaw dashboard`
+然后在浏览器中聊天，或打开 `http://127.0.0.1:18789/` （在 Gateway网关主机上）。
+文档： [仪表盘](/web/dashboard) 和 [控制界面](/web/control-ui)。
+
+推荐路径：使用 **CLI 新手引导向导** （`openclaw onboard`）。它会设置：
+
+- 模型/认证（推荐使用 OAuth）
+- Gateway网关设置
+- 渠道（WhatsApp/Telegram/Discord/Mattermost（插件）/...）
+- 配对默认设置（安全私信）
+- 工作区引导 + Skills
+- 可选的后台服务
+
+如果你需要更详细的参考页面，请跳转至： [向导](/start/wizard), [设置](/start/setup), [配对](/start/pairing), [安全](/gateway/security)。
+
+沙盒注意事项： `agents.defaults.sandbox.mode: "non-main"` 使用 `session.mainKey` （默认 `"main"`），因此群组/渠道会话是沙箱隔离的。如果你希望主智能体始终在主机上运行，请设置显式的逐智能体覆盖：
+
+```json
+{
+  "routing": {
+    "agents": {
+      "main": {
+        "workspace": "~/.openclaw/workspace",
+        "sandbox": { "mode": "off" }
+      }
+    }
+  }
+}
+```
+
+## 0）前提条件
+
+- Node `>=22`
+- `pnpm` （可选；如果从源码构建则推荐安装）
+- **推荐：** Brave Search API 密钥用于网络搜索。最简单的方式：
+  `openclaw configure --section web` （存储 `tools.web.search.apiKey`）。
+  参见 [网络工具](/tools/web)。
+
+macOS：如果你计划构建应用程序，请安装 Xcode / CLT。如果仅使用 CLI + Gateway网关，Node 就足够了。
+Windows：使用 **WSL2** （推荐 Ubuntu）。强烈推荐使用 WSL2；原生 Windows 未经测试，问题较多，且工具兼容性较差。请先安装 WSL2，然后在 WSL 内执行 Linux 步骤。参见 [Windows (WSL2)](/platforms/windows)。
+
+## 1）安装 CLI（推荐）
+
+```bash
+curl -fsSL https://openclaw.bot/install.sh | bash
+```
+
+安装选项（安装方式、非交互式、从 GitHub 安装）： [安装](/install)。
+
+Windows (PowerShell)：
+
+```powershell
+iwr -useb https://openclaw.ai/install.ps1 | iex
+```
+
+替代方式（全局安装）：
+
+```bash
+npm install -g openclaw@latest
+```
+
+```bash
+pnpm add -g openclaw@latest
+```
+
+## 2）运行新手引导向导（并安装服务）
+
+```bash
+openclaw onboard --install-daemon
+```
+
+你需要选择的内容：
+
+- **本地 vs 远程** Gateway网关
+- **认证**：OpenAI Code (Codex) 订阅（OAuth）或 API 密钥。对于 Anthropic，我们推荐使用 API 密钥； `claude setup-token` 也受支持。
+- **提供商**：WhatsApp 二维码登录、Telegram/Discord 机器人令牌、Mattermost 插件令牌等。
+- **守护进程**：后台安装（launchd/systemd；WSL2 使用 systemd）
+  - **运行时**：Node（推荐；WhatsApp/Telegram 必需）。Bun 为 **不推荐**。
+- **Gateway网关令牌**：向导默认会生成一个（即使在 local loopback 上）并将其存储在 `gateway.auth.token`。
+
+向导文档： [向导](/start/wizard)
+
+### 凭证：存储位置（重要）
+
+- **推荐的 Anthropic 路径：** 设置 API 密钥（向导可以将其存储以供服务使用）。 `claude setup-token`：你可以复用 Claude Code 凭据。
+
+- OAuth 凭据（旧版导入）： `~/.openclaw/credentials/oauth.json`
+- 认证配置文件（OAuth + API 密钥）： `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
+
+无头/服务器提示：先在普通机器上完成 OAuth，然后复制 `oauth.json` 到 Gateway网关主机上。
+
+## 3）启动 Gateway网关如果你在新手引导过程中安装了服务，Gateway网关应该已经在运行：
+
+```bash
+openclaw gateway status
+```
+
+手动运行（前台）：
+
+```bash
+openclaw gateway --port 18789 --verbose
+```
+
+仪表盘（本地 local loopback）： `http://127.0.0.1:18789/`
+如果配置了令牌，请将其粘贴到控制界面设置中（存储为 `connect.params.auth.token`）。
+
+⚠️ **Bun 警告（WhatsApp + Telegram）：** Bun 在这些渠道上存在已知问题。如果你使用 WhatsApp 或 Telegram，请使用 **Node **。
+
+## 3.5）快速验证（2 分钟）
+
+```bash
+openclaw status
+openclaw health
+openclaw security audit --deep
+```
+
+## 4）配对 + 连接你的第一个聊天界面
+
+### WhatsApp（二维码登录）
+
+```bash
+openclaw channels login
+```
+
+通过 WhatsApp → 设置 → 已关联设备 进行扫描。
+
+WhatsApp 文档： [WhatsApp](/channels/whatsapp)
+
+### Telegram / Discord / 其他
+
+向导可以为你写入令牌/配置。如果你更喜欢手动配置，请从以下内容开始：
+
+- Telegram： [Telegram](/channels/telegram)
+- Discord： [Discord](/channels/discord)
+- Mattermost（插件）： [Mattermost](/channels/mattermost)
+
+**Telegram 私信提示：** 你的第一条私信会返回一个配对码。请批准它（参见下一步），否则机器人将不会响应。
+
+## 5）私信安全（配对审批）
+
+默认策略：未知私信会收到一个短码，消息在批准之前不会被处理。
+如果你的第一条私信没有收到回复，请批准配对：
+
+```bash
+openclaw pairing list whatsapp
+openclaw pairing approve whatsapp <code>
+```
+
+配对文档： [配对](/start/pairing)
+
+## 从源码安装（开发）
+
+如果你正在开发 OpenClaw 本身，请从源码运行：
+
+```bash
+git clone https://github.com/openclaw/openclaw.git
+cd openclaw
+pnpm install
+pnpm ui:build # auto-installs UI deps on first run
+pnpm build
+openclaw onboard --install-daemon
+```
+
+如果你尚未进行全局安装，请通过以下方式运行新手引导流程 `pnpm openclaw ...` （从仓库中）。
+`pnpm build` 也会打包 A2UI 资源；如果你只需要运行该步骤，请使用 `pnpm canvas:a2ui:bundle`。
+
+Gateway网关（从此仓库）：
+
+```bash
+node openclaw.mjs gateway --port 18789 --verbose
+```
+
+## 7）端到端验证
+
+在新终端中，发送一条测试消息：
+
+```bash
+openclaw message send --target +15555550123 --message "Hello from OpenClaw"
+```
+
+如果 `openclaw health` 显示"未配置认证"，请返回向导设置 OAuth/密钥认证——智能体在没有认证的情况下将无法响应。
+
+提示： `openclaw status --all` 是最佳的可粘贴只读调试报告。
+健康探针： `openclaw health` （或 `openclaw status --deep`）向运行中的 Gateway网关请求健康快照。
+
+## 后续步骤（可选，但强烈推荐）
+
+- macOS 菜单栏应用 + 语音唤醒： [macOS 应用](/platforms/macos)
+- iOS/Android 节点（Canvas/相机/语音）： [节点](/nodes)
+- 远程访问（SSH 隧道 / Tailscale Serve）： [远程访问](/gateway/remote) 和 [Tailscale](/gateway/tailscale)
+- 常驻运行 / VPN 设置： [远程访问](/gateway/remote), [exe.dev](/platforms/exe-dev), [Hetzner](/platforms/hetzner), [macOS 远程](/platforms/mac/remote)