@gguf/claw 2026.2.1 → 2026.2.3

package/docs/zh-CN/index.md

@@ -0,0 +1,268 @@
+---
+read_when:
+  - 向新用户介绍 OpenClaw
+summary: OpenClaw 的顶层概述、功能特性与用途
+title: OpenClaw
+x-i18n:
+  generated_at: "2026-02-01T13:34:09Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 92462177964ac72c344d3e8613a3756bc8e06eb7844cda20a38cd43e7cadd3b2
+  source_path: index.md
+  workflow: 9
+---
+
+# OpenClaw 🦞
+
+> _"EXFOLIATE! EXFOLIATE!"_ — 大概是一只太空龙虾说的
+
+> **中文文档提示：** 本页及其他中文文档由自动化翻译流水线生成。如果你发现翻译问题，请在 [#6995](https://github.com/openclaw/openclaw/issues/6995) 反馈（不要提交 PR）。我们正在积极扩展对中文用户、模型与消息平台的支持，更多内容即将推出！需要支持请到 Discord 的 [#help-中文](https://discord.com/channels/1456350064065904867/1466722439789674741)。
+
+<p align="center">
+    <img
+        src="/assets/openclaw-logo-text-dark.png"
+        alt="OpenClaw"
+        width="500"
+        class="dark:hidden"
+    />
+    <img
+        src="/assets/openclaw-logo-text.png"
+        alt="OpenClaw"
+        width="500"
+        class="hidden dark:block"
+    />
+</p>
+
+<p align="center">
+  <strong>适用于任意操作系统，通过 WhatsApp/Telegram/Discord/iMessage Gateway网关连接 AI 智能体 (Pi)。</strong><br />
+  插件可添加 Mattermost 等更多渠道支持。
+  发送一条消息，即可获得智能体回复——随时随地，触手可及。
+</p>
+
+<p align="center">
+  <a href="https://github.com/openclaw/openclaw">GitHub</a> ·
+  <a href="https://github.com/openclaw/openclaw/releases">版本发布</a> ·
+  <a href="/">文档</a> ·
+  <a href="/start/openclaw">OpenClaw 助手设置</a>
+</p>
+
+OpenClaw 将 WhatsApp（通过 WhatsApp Web / Baileys）、Telegram（Bot API / grammY）、Discord（Bot API / channels.discord.js）和 iMessage（imsg CLI）桥接至编程智能体，例如 [Pi](https://github.com/badlogic/pi-mono)。插件可添加 Mattermost（Bot API + WebSocket）等更多渠道支持。
+OpenClaw 同时也驱动着 OpenClaw 助手。
+
+## 从这里开始
+
+- **从零开始全新安装：** [入门指南](/start/getting-started)
+- **引导式设置（推荐）：** [向导](/start/wizard) （`openclaw onboard`）
+- **打开仪表盘（本地 Gateway网关）：** http://127.0.0.1:18789/（或 http://localhost:18789/）
+
+如果 Gateway网关运行在这台计算机上，该链接会立即打开浏览器控制界面。如果无法打开，请先启动 Gateway网关： `openclaw gateway`.
+
+## 仪表盘（浏览器控制界面）
+
+仪表盘是用于聊天、配置、节点、会话等功能的浏览器控制界面。
+本地默认地址：http://127.0.0.1:18789/
+远程访问： [Web 界面](/web) 和 [Tailscale](/gateway/tailscale)
+
+<p align="center">
+  <img src="/whatsapp-openclaw.jpg" alt="OpenClaw（英文原图）" width="360" />
+  <img src="/whatsapp-openclaw-ai-zh.jpg" alt="OpenClaw（AI 自动翻译）" width="360" />
+  <br />
+  <em>左：英文原图 · 右：AI 自动翻译（玩笑版）</em>
+</p>
+
+## 工作原理
+
+```
+WhatsApp / Telegram / Discord / iMessage (+ plugins)
+        │
+        ▼
+  ┌───────────────────────────┐
+  │          Gateway网关          │  ws://127.0.0.1:18789 (loopback-only)
+  │     (single source)       │
+  │                           │  http://<gateway-host>:18793
+  │                           │    /__openclaw__/canvas/ (Canvas host)
+  └───────────┬───────────────┘
+              │
+              ├─ Pi agent (RPC)
+              ├─ CLI (openclaw …)
+              ├─ Chat UI (SwiftUI)
+              ├─ macOS app (OpenClaw.app)
+              ├─ iOS node via Gateway网关 WS + pairing
+              └─ Android node via Gateway网关 WS + pairing
+```
+
+大多数操作通过 **Gateway网关** （`openclaw gateway`进行，它是一个长期运行的单进程，负责管理渠道连接和 WebSocket 控制面。
+
+## 网络模型
+
+- **每台主机一个 Gateway网关（推荐）**：它是唯一允许持有 WhatsApp Web 会话的进程。如果需要备用机器人或严格隔离，可使用独立配置文件和端口运行多个 Gateway网关；请参阅 [多 Gateway网关部署](/gateway/multiple-gateways).
+- **优先 local loopback**：Gateway网关 WS 默认监听 `ws://127.0.0.1:18789`.
+  - 向导现在默认会生成一个 Gateway网关令牌（即使在 local loopback 模式下也是如此）。
+  - 如需 Tailnet 访问，请运行 `openclaw gateway --bind tailnet --token ...` （非 local loopback 绑定时必须提供令牌）。
+- **节点**：通过 WebSocket 连接到 Gateway网关（根据需要使用局域网/Tailnet/SSH）；旧版 TCP 桥接已弃用/移除。
+- **Canvas 主机**：HTTP 文件服务器运行在 `canvasHost.port` （默认 `18793`），提供 `/__openclaw__/canvas/` 用于节点 WebView；请参阅 [Gateway网关配置](/gateway/configuration) （`canvasHost`）。
+- **远程使用**：SSH 隧道或 Tailnet/VPN；请参阅 [远程访问](/gateway/remote) 和 [发现机制](/gateway/discovery).
+
+## 功能特性（概览）
+
+- 📱 **WhatsApp 集成** — 使用 Baileys 实现 WhatsApp Web 协议
+- ✈️ **Telegram 机器人** — 通过 grammY 支持私聊和群组
+- 🎮 **Discord 机器人** — 通过 channels.discord.js 支持私聊和服务器频道
+- 🧩 **Mattermost 机器人（插件）** — Bot 令牌 + WebSocket 事件
+- 💬 **iMessage** — 本地 imsg CLI 集成（macOS）
+- 🤖 **智能体桥接** — Pi（RPC 模式），支持工具流式传输
+- ⏱️ **流式传输与分块** — 区块流传输 + Telegram 草稿流式传输详情（[/concepts/streaming](/concepts/streaming)）
+- 🧠 **多智能体路由** — 将提供商账户/对等方路由到隔离的智能体（工作区 + 每智能体会话）
+- 🔐 **订阅认证** — 通过 OAuth 支持 Anthropic（Claude Pro/Max）+ OpenAI（ChatGPT/Codex）
+- 💬 **会话** — 私聊折叠为共享 `main` （默认）；群组为隔离
+- 👥 **群聊支持** — 默认基于提及触发；所有者可切换 `/activation always|mention`
+- 📎 **媒体支持** — 收发图片、音频、文档
+- 🎤 **语音消息** — 可选的转录钩子
+- 🖥️ **网页聊天 + macOS 应用** — 本地界面 + 菜单栏辅助工具，支持操作和语音唤醒
+- 📱 **iOS 节点** — 作为节点配对并提供 Canvas 界面
+- 📱 **Android 节点** — 作为节点配对并提供 Canvas + 聊天 + 相机
+
+注意：旧版 Claude/Codex/Gemini/Opencode 路径已移除；Pi 是唯一的编程智能体路径。
+
+## 快速开始
+
+运行时要求： **Node ≥ 22**.
+
+```bash
+# Recommended: global install (npm/pnpm)
+npm install -g openclaw@latest
+# or: pnpm add -g openclaw@latest
+
+# Onboard + install the service (launchd/systemd user service)
+openclaw onboard --install-daemon
+
+# Pair WhatsApp Web (shows QR)
+openclaw channels login
+
+# Gateway网关 runs via the service after onboarding; manual run is still possible:
+openclaw gateway --port 18789
+```
+
+之后在 npm 安装和 git 安装之间切换很简单：安装另一种方式并运行 `openclaw doctor` 以更新 Gateway网关服务入口点。
+
+从源码安装（开发）：
+
+```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 ...` （在仓库目录中执行）。
+
+多实例快速开始（可选）：
+
+```bash
+OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \
+OPENCLAW_STATE_DIR=~/.openclaw-a \
+openclaw gateway --port 19001
+```
+
+发送测试消息（需要 Gateway网关正在运行）：
+
+```bash
+openclaw message send --target +15555550123 --message "Hello from OpenClaw"
+```
+
+## 配置（可选）
+
+配置文件位于 `~/.openclaw/openclaw.json`.
+
+- 如果你 **不做任何操作**，OpenClaw 将使用内置的 Pi 二进制文件以 RPC 模式运行，并采用按发送者区分的会话。
+- 如果你想锁定访问权限，请从以下内容开始 `channels.whatsapp.allowFrom` 以及（针对群组的）提及规则。
+
+示例：
+
+```json5
+{
+  channels: {
+    whatsapp: {
+      allowFrom: ["+15555550123"],
+      groups: { "*": { requireMention: true } },
+    },
+  },
+  messages: { groupChat: { mentionPatterns: ["@openclaw"] } },
+}
+```
+
+## 文档
+
+- 从这里开始：
+  - [文档中心（所有页面链接）](/start/hubs)
+  - [帮助](/help) ← _常见修复方案 + 故障排除_
+  - [配置](/gateway/configuration)
+  - [配置示例](/gateway/configuration-examples)
+  - [斜杠命令](/tools/slash-commands)
+  - [多智能体路由](/concepts/multi-agent)
+  - [更新 / 回滚](/install/updating)
+  - [配对（私聊 + 节点）](/start/pairing)
+  - [Nix 模式](/install/nix)
+  - [OpenClaw 助手设置](/start/openclaw)
+  - [Skills](/tools/skills)
+  - [Skills配置](/tools/skills-config)
+  - [工作区模板](/reference/templates/AGENTS)
+  - [RPC 适配器](/reference/rpc)
+  - [Gateway网关运维手册](/gateway)
+  - [节点（iOS/Android）](/nodes)
+  - [Web 界面（控制界面）](/web)
+  - [发现机制 + 传输方式](/gateway/discovery)
+  - [远程访问](/gateway/remote)
+- 提供商与用户体验：
+  - [网页聊天](/web/webchat)
+  - [控制界面（浏览器）](/web/control-ui)
+  - [Telegram](/channels/telegram)
+  - [Discord](/channels/discord)
+  - [Mattermost（插件）](/channels/mattermost)
+  - [iMessage](/channels/imessage)
+  - [群组](/concepts/groups)
+  - [WhatsApp 群组消息](/concepts/group-messages)
+  - [媒体：图片](/nodes/images)
+  - [媒体：音频](/nodes/audio)
+- 伴侣应用：
+  - [macOS 应用](/platforms/macos)
+  - [iOS 应用](/platforms/ios)
+  - [Android 应用](/platforms/android)
+  - [Windows (WSL2)](/platforms/windows)
+  - [Linux 应用](/platforms/linux)
+- 运维与安全：
+  - [会话](/concepts/session)
+  - [定时任务](/automation/cron-jobs)
+  - [Webhooks](/automation/webhook)
+  - [Gmail 钩子（Pub/Sub）](/automation/gmail-pubsub)
+  - [安全](/gateway/security)
+  - [故障排除](/gateway/troubleshooting)
+
+## 名称由来
+
+**OpenClaw = CLAW + TARDIS** — 因为每只太空龙虾都需要一台时空机器。
+
+---
+
+_"我们都只是在玩弄自己的提示词罢了。"_ — 大概是一个嗑多了 token 的 AI 说的
+
+## 致谢
+
+- **Peter Steinberger** （[@steipete](https://twitter.com/steipete)）— 创作者，龙虾低语者
+- **Mario Zechner** （[@badlogicc](https://twitter.com/badlogicgames)）— Pi 创作者，安全渗透测试员
+- **Clawd** — 那只要求取个更好名字的太空龙虾
+
+## 核心贡献者
+
+- **Maxim Vovshin** (@Hyaxia, 36747317+Hyaxia@users.noreply.github.com）— Blogwatcher Skills
+- **Nacho Iacovino** (@nachoiacovino, nacho.iacovino@gmail.com）— 位置解析（Telegram + WhatsApp）
+
+## 许可证
+
+MIT — 像大海中的龙虾一样自由 🦞
+
+---
+
+_"我们都只是在玩弄自己的提示词罢了。"_ — 大概是一个嗑多了 token 的 AI 说的

package/docs/zh-CN/install/ansible.md

@@ -0,0 +1,215 @@
+---
+read_when:
+  - 你需要通过安全加固进行自动化服务器部署
+  - 你需要带 VPN 访问的防火墙隔离设置
+  - 你要部署到远程 Debian/Ubuntu 服务器
+summary: 使用 Ansible、Tailscale VPN 和防火墙隔离进行自动化、安全加固的 OpenClaw 安装
+title: Ansible
+x-i18n:
+  generated_at: "2026-02-01T21:05:32Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 896807f344d923f09039f377c13b4bf4a824aa94eec35159fc169596a3493b29
+  source_path: install/ansible.md
+  workflow: 14
+---
+
+# Ansible 安装
+
+将 OpenClaw 部署到生产服务器的推荐方式是使用 **[openclaw-ansible](https://github.com/openclaw/openclaw-ansible)** — 一个采用安全优先架构的自动化安装工具。
+
+## 快速开始
+
+一条命令安装：
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/openclaw/openclaw-ansible/main/install.sh | bash
+```
+
+> **📦 完整指南：[github.com/openclaw/openclaw-ansible](https://github.com/openclaw/openclaw-ansible)**
+>
+> openclaw-ansible 仓库是 Ansible 部署的权威来源。本页面仅为简要概览。
+
+## 你将获得
+
+- 🔒 **防火墙优先的安全策略**：UFW + Docker 隔离（仅 SSH + Tailscale 可访问）
+- 🔐 **Tailscale VPN**：安全的远程访问，无需公开暴露服务
+- 🐳 **Docker**：隔离的沙箱容器，仅绑定 localhost
+- 🛡️ **纵深防御**：4 层安全架构
+- 🚀 **一条命令部署**：几分钟内完成完整部署
+- 🔧 **Systemd 集成**：开机自启并带有安全加固
+
+## 前置要求
+
+- **操作系统**：Debian 11+ 或 Ubuntu 20.04+
+- **访问权限**：Root 或 sudo 权限
+- **网络**：用于安装软件包的互联网连接
+- **Ansible**：2.14+（快速启动脚本会自动安装）
+
+## 安装内容
+
+Ansible playbook 会安装并配置以下组件：
+
+1. **Tailscale**（用于安全远程访问的 mesh VPN）
+2. **UFW 防火墙**（仅开放 SSH + Tailscale 端口）
+3. **Docker CE + Compose V2**（用于智能体沙箱）
+4. **Node.js 22.x + pnpm**（运行时依赖）
+5. **OpenClaw**（基于主机安装，非容器化）
+6. **Systemd 服务**（带安全加固的自动启动）
+
+注意：Gateway网关 **直接运行在主机上**（不在 Docker 中），但智能体沙箱使用 Docker 进行隔离。详见 [沙箱](/gateway/sandboxing)。
+
+## 安装后设置
+
+安装完成后，切换到 openclaw 用户：
+
+```bash
+sudo -i -u openclaw
+```
+
+安装后脚本将引导你完成：
+
+1. **新手引导向导**：配置 OpenClaw 设置
+2. **提供商登录**：连接 WhatsApp/Telegram/Discord/Signal
+3. **Gateway网关测试**：验证安装
+4. **Tailscale 设置**：连接到你的 VPN mesh 网络
+
+### 常用命令
+
+```bash
+# 检查服务状态
+sudo systemctl status openclaw
+
+# 查看实时日志
+sudo journalctl -u openclaw -f
+
+# 重启 Gateway网关
+sudo systemctl restart openclaw
+
+# 提供商登录（以 openclaw 用户运行）
+sudo -i -u openclaw
+openclaw channels login
+```
+
+## 安全架构
+
+### 4 层防御
+
+1. **防火墙（UFW）**：仅公开暴露 SSH (22) + Tailscale (41641/udp)
+2. **VPN（Tailscale）**：Gateway网关仅可通过 VPN mesh 网络访问
+3. **Docker 隔离**：DOCKER-USER iptables 链阻止外部端口暴露
+4. **Systemd 加固**：NoNewPrivileges、PrivateTmp、非特权用户
+
+### 验证
+
+测试外部攻击面：
+
+```bash
+nmap -p- YOUR_SERVER_IP
+```
+
+应当仅显示**端口 22**（SSH）为开放状态。所有其他服务（Gateway网关、Docker）均已锁定。
+
+### Docker 可用性
+
+Docker 用于**智能体沙箱**（隔离的工具执行），而非运行 Gateway网关本身。Gateway网关仅绑定到 localhost，通过 Tailscale VPN 访问。
+
+沙箱配置详见 [多智能体沙箱与工具](/multi-agent-sandbox-tools)。
+
+## 手动安装
+
+如果你希望手动控制而非使用自动化：
+
+```bash
+# 1. 安装前置依赖
+sudo apt update && sudo apt install -y ansible git
+
+# 2. 克隆仓库
+git clone https://github.com/openclaw/openclaw-ansible.git
+cd openclaw-ansible
+
+# 3. 安装 Ansible 集合
+ansible-galaxy collection install -r requirements.yml
+
+# 4. 运行 playbook
+./run-playbook.sh
+
+# 或直接运行（之后手动执行 /tmp/openclaw-setup.sh）
+# ansible-playbook playbook.yml --ask-become-pass
+```
+
+## 更新 OpenClaw
+
+Ansible 安装程序将 OpenClaw 设置为手动更新。标准更新流程详见 [更新](/install/updating)。
+
+重新运行 Ansible playbook（例如配置变更时）：
+
+```bash
+cd openclaw-ansible
+./run-playbook.sh
+```
+
+注意：此操作是幂等的，可以安全地多次运行。
+
+## 故障排除
+
+### 防火墙阻止了我的连接
+
+如果你被锁定在外：
+
+- 确保先通过 Tailscale VPN 访问
+- SSH 访问（端口 22）始终是允许的
+- Gateway网关 **仅**可通过 Tailscale 访问，这是设计如此
+
+### 服务无法启动
+
+```bash
+# 检查日志
+sudo journalctl -u openclaw -n 100
+
+# 验证权限
+sudo ls -la /opt/openclaw
+
+# 测试手动启动
+sudo -i -u openclaw
+cd ~/openclaw
+pnpm start
+```
+
+### Docker 沙箱问题
+
+```bash
+# 验证 Docker 是否运行
+sudo systemctl status docker
+
+# 检查沙箱镜像
+sudo docker images | grep openclaw-sandbox
+
+# 如果缺少沙箱镜像则构建
+cd /opt/openclaw/openclaw
+sudo -u openclaw ./scripts/sandbox-setup.sh
+```
+
+### 提供商登录失败
+
+确保你以 `openclaw` 用户运行：
+
+```bash
+sudo -i -u openclaw
+openclaw channels login
+```
+
+## 高级配置
+
+有关详细的安全架构和故障排除：
+
+- [安全架构](https://github.com/openclaw/openclaw-ansible/blob/main/docs/security.md)
+- [技术细节](https://github.com/openclaw/openclaw-ansible/blob/main/docs/architecture.md)
+- [故障排除指南](https://github.com/openclaw/openclaw-ansible/blob/main/docs/troubleshooting.md)
+
+## 相关内容
+
+- [openclaw-ansible](https://github.com/openclaw/openclaw-ansible) — 完整部署指南
+- [Docker](/install/docker) — 容器化 Gateway网关设置
+- [沙箱](/gateway/sandboxing) — 智能体沙箱配置
+- [多智能体沙箱与工具](/multi-agent-sandbox-tools) — 按智能体隔离

package/docs/zh-CN/install/bun.md

@@ -0,0 +1,65 @@
+---
+read_when:
+  - 你想要最快的本地开发循环（bun + watch）
+  - 你遇到了 Bun 安装/补丁/生命周期脚本问题
+summary: Bun 工作流（实验性）：安装方式及与 pnpm 相比的注意事项
+title: Bun（实验性）
+x-i18n:
+  generated_at: "2026-02-01T21:05:42Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: eb3f4c222b6bae49938d8bf53a0818fe5f5e0c0c3c1adb3e0a832ce8f785e1e3
+  source_path: install/bun.md
+  workflow: 14
+---
+
+# Bun（实验性）
+
+目标：使用 **Bun** 运行本仓库（可选，不推荐用于 WhatsApp/Telegram），同时不偏离 pnpm 工作流。
+
+⚠️ **不推荐用于 Gateway网关运行时**（WhatsApp/Telegram 存在 bug）。生产环境请使用 Node。
+
+## 状态
+
+- Bun 是一个可选的本地运行时，用于直接运行 TypeScript（`bun run …`、`bun --watch …`）。
+- `pnpm` 是默认的构建工具，仍然完全受支持（部分文档工具也在使用）。
+- Bun 无法使用 `pnpm-lock.yaml`，会将其忽略。
+
+## 安装
+
+默认方式：
+
+```sh
+bun install
+```
+
+注意：`bun.lock`/`bun.lockb` 已被 gitignore，因此不会造成仓库变动。如果你不想写入锁文件：
+
+```sh
+bun install --no-save
+```
+
+## 构建 / 测试（Bun）
+
+```sh
+bun run build
+bun run vitest run
+```
+
+## Bun 生命周期脚本（默认被阻止）
+
+Bun 可能会阻止依赖的生命周期脚本，除非显式信任（`bun pm untrusted` / `bun pm trust`）。
+对于本仓库，常见被阻止的脚本并非必需：
+
+- `@whiskeysockets/baileys` `preinstall`：检查 Node 主版本 >= 20（我们运行 Node 22+）。
+- `protobufjs` `postinstall`：发出关于不兼容版本方案的警告（无构建产物）。
+
+如果你遇到确实需要这些脚本的运行时问题，请显式信任它们：
+
+```sh
+bun pm trust @whiskeysockets/baileys protobufjs
+```
+
+## 注意事项
+
+- 部分脚本仍硬编码使用 pnpm（例如 `docs:build`、`ui:*`、`protocol:check`）。目前请通过 pnpm 运行这些脚本。

package/docs/zh-CN/install/development-channels.md

@@ -0,0 +1,79 @@
+---
+read_when:
+  - 你想在稳定版/测试版/开发版之间切换
+  - 你正在标记或发布预发布版本
+summary: 稳定版、测试版和开发版渠道：语义、切换和标签管理
+title: 开发渠道
+x-i18n:
+  generated_at: "2026-02-01T21:05:54Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 2b01219b7e705044ce39838a0da7c7fa65c719809ab2f8a51e14529064af81bf
+  source_path: install/development-channels.md
+  workflow: 14
+---
+
+# 开发渠道
+
+最后更新：2026-01-21
+
+OpenClaw 提供三个更新渠道：
+
+- **stable**：npm dist-tag `latest`。
+- **beta**：npm dist-tag `beta`（测试中的构建）。
+- **dev**：`main` 分支的最新提交（git）。npm dist-tag：`dev`（发布时）。
+
+我们将构建发布到 **beta**，进行测试，然后**将经过验证的构建提升为 `latest`**，无需更改版本号 — dist-tag 是 npm 安装的权威来源。
+
+## 切换渠道
+
+Git checkout 方式：
+
+```bash
+openclaw update --channel stable
+openclaw update --channel beta
+openclaw update --channel dev
+```
+
+- `stable`/`beta` 会签出最新匹配的标签（通常是同一个标签）。
+- `dev` 切换到 `main` 并在上游基础上进行 rebase。
+
+npm/pnpm 全局安装方式：
+
+```bash
+openclaw update --channel stable
+openclaw update --channel beta
+openclaw update --channel dev
+```
+
+这会通过对应的 npm dist-tag（`latest`、`beta`、`dev`）进行更新。
+
+当你**显式**使用 `--channel` 切换渠道时，OpenClaw 也会同步调整安装方式：
+
+- `dev` 确保存在 git checkout（默认 `~/openclaw`，可通过 `OPENCLAW_GIT_DIR` 覆盖），更新它，并从该 checkout 安装全局 CLI。
+- `stable`/`beta` 使用匹配的 dist-tag 从 npm 安装。
+
+提示：如果你想同时使用 stable 和 dev，可以保留两个克隆，并将 Gateway网关指向 stable 的那个。
+
+## 插件与渠道
+
+使用 `openclaw update` 切换渠道时，OpenClaw 也会同步插件来源：
+
+- `dev` 优先使用 git checkout 中内置的插件。
+- `stable` 和 `beta` 恢复通过 npm 安装的插件包。
+
+## 标签最佳实践
+
+- 为你希望 git checkout 落到的版本打标签（`vYYYY.M.D` 或 `vYYYY.M.D-<patch>`）。
+- 保持标签不可变：永远不要移动或重用标签。
+- npm dist-tag 仍然是 npm 安装的权威来源：
+  - `latest` → 稳定版
+  - `beta` → 候选构建
+  - `dev` → main 快照（可选）
+
+## macOS 应用可用性
+
+测试版和开发版构建可能**不包含** macOS 应用发布。这是正常的：
+
+- git 标签和 npm dist-tag 仍然可以发布。
+- 在发布说明或变更日志中注明"此测试版无 macOS 构建"即可。