@quantumclaw/quantumclaw 2026.3.22

package/docs/zh-CN/platforms/raspberry-pi.md

@@ -0,0 +1,416 @@
+---
+read_when:
+  - 在 Raspberry Pi 上设置 QuantumClaw
+  - 在 ARM 设备上运行 QuantumClaw
+  - 构建一个低成本、始终在线的个人 AI
+summary: 在 Raspberry Pi 上运行 QuantumClaw（低预算自托管方案）
+title: Raspberry Pi
+x-i18n:
+  generated_at: "2026-03-16T06:24:58Z"
+  model: gpt-5.4
+  provider: openai
+  source_hash: 3106dea63b5a548622b82e3090e7fdb7f748b96bf0e23893496f1b60c095334a
+  source_path: platforms/raspberry-pi.md
+  workflow: 15
+---
+
+# 在 Raspberry Pi 上运行 QuantumClaw
+
+## 目标
+
+在 Raspberry Pi 上以 **约 35–80 美元**的一次性成本（无月费）运行一个持久化、始终在线的 QuantumClaw Gateway 网关。
+
+非常适合：
+
+- 7×24 个人 AI 助手
+- 家庭自动化中枢
+- 低功耗、始终可用的 Telegram/WhatsApp bot
+
+## 硬件要求
+
+| Pi 型号         | RAM     | 可用？  | 说明                       |
+| --------------- | ------- | ------- | -------------------------- |
+| **Pi 5**        | 4GB/8GB | ✅ 最佳 | 最快，推荐                 |
+| **Pi 4**        | 4GB     | ✅ 良好 | 适合大多数用户的最佳平衡点 |
+| **Pi 4**        | 2GB     | ✅ 可以 | 可用，建议加 swap          |
+| **Pi 4**        | 1GB     | ⚠️ 紧张 | 配合 swap 和最小化配置可行 |
+| **Pi 3B+**      | 1GB     | ⚠️ 较慢 | 可用，但反应迟缓           |
+| **Pi Zero 2 W** | 512MB   | ❌      | 不推荐                     |
+
+**最低规格：** 1 GB RAM、1 核、500 MB 磁盘  
+**推荐规格：** 2 GB 以上 RAM、64 位 OS、16 GB 以上 SD 卡（或 USB SSD）
+
+## 你需要准备的内容
+
+- Raspberry Pi 4 或 5（推荐 2 GB 以上）
+- MicroSD 卡（16 GB 以上）或 USB SSD（性能更好）
+- 电源（推荐使用官方 Pi 电源）
+- 网络连接（以太网或 Wi‑Fi）
+- 约 30 分钟
+
+## 1）刷写 OS
+
+使用 **Raspberry Pi OS Lite（64 位）** —— 对于无头服务器，不需要桌面环境。
+
+1. 下载 [Raspberry Pi Imager](https://www.raspberrypi.com/software/)
+2. 选择 OS：**Raspberry Pi OS Lite（64 位）**
+3. 点击齿轮图标（⚙️）进行预配置：
+   - 设置主机名：`gateway-host`
+   - 启用 SSH
+   - 设置用户名/密码
+   - 配置 Wi‑Fi（如果不使用以太网）
+4. 将系统写入你的 SD 卡 / USB 驱动器
+5. 插入并启动 Pi
+
+## 2）通过 SSH 连接
+
+```bash
+ssh user@gateway-host
+# 或使用 IP 地址
+ssh user@192.168.x.x
+```
+
+## 3）系统设置
+
+```bash
+# 更新系统
+sudo apt update && sudo apt upgrade -y
+
+# 安装基础软件包
+sudo apt install -y git curl build-essential
+
+# 设置时区（对 cron/提醒很重要）
+sudo timedatectl set-timezone America/Chicago  # 改成你的时区
+```
+
+## 4）安装 Node.js 24（ARM64）
+
+```bash
+# 通过 NodeSource 安装 Node.js
+curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
+sudo apt install -y nodejs
+
+# 验证
+node --version  # 应显示 v24.x.x
+npm --version
+```
+
+## 5）添加 swap（对于 2 GB 或更低内存很重要）
+
+swap 可以防止内存不足崩溃：
+
+```bash
+# 创建 2 GB swap 文件
+sudo fallocate -l 2G /swapfile
+sudo chmod 600 /swapfile
+sudo mkswap /swapfile
+sudo swapon /swapfile
+
+# 永久生效
+echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
+
+# 针对低内存优化（降低 swappiness）
+echo 'vm.swappiness=10' | sudo tee -a /etc/sysctl.conf
+sudo sysctl -p
+```
+
+## 6）安装 QuantumClaw
+
+### 选项 A：标准安装（推荐）
+
+```bash
+curl -fsSL https://quantumclaw.ai/install.sh | bash
+```
+
+### 选项 B：可修改安装（适合折腾）
+
+```bash
+git clone https://github.com/quantumclaw/quantumclaw.git
+cd quantumclaw
+npm install
+npm run build
+npm link
+```
+
+可修改安装会让你直接访问日志和代码 —— 这对于调试 ARM 特定问题很有帮助。
+
+## 7）运行新手引导
+
+```bash
+quantumclaw onboard --install-daemon
+```
+
+按向导完成设置：
+
+1. **Gateway 网关模式：** Local
+2. **认证：** 推荐 API key（在无头 Pi 上 OAuth 可能比较挑环境）
+3. **渠道：** 最容易上手的是 Telegram
+4. **守护进程：** 是（systemd）
+
+## 8）验证安装
+
+```bash
+# 检查状态
+quantumclaw status
+
+# 检查服务
+sudo systemctl status quantumclaw
+
+# 查看日志
+journalctl -u quantumclaw -f
+```
+
+## 9）访问 QuantumClaw Dashboard
+
+将 `user@gateway-host` 替换为你的 Pi 用户名，以及主机名或 IP 地址。
+
+在你的电脑上，让 Pi 打印一个新的 Dashboard URL：
+
+```bash
+ssh user@gateway-host 'quantumclaw dashboard --no-open'
+```
+
+该命令会打印 `Dashboard URL:`。根据 `gateway.auth.token`
+的配置方式，URL 可能是普通的 `http://127.0.0.1:18789/` 链接，也可能是包含 `#token=...` 的链接。
+
+在你电脑上的另一个终端中，创建 SSH 隧道：
+
+```bash
+ssh -N -L 18789:127.0.0.1:18789 user@gateway-host
+```
+
+然后在本地浏览器中打开打印出的 Dashboard URL。
+
+如果 UI 要求认证，请将 `gateway.auth.token`
+（或 `QUANTUMCLAW_GATEWAY_TOKEN`）中的 token 粘贴到 Control UI 设置中。
+
+如需始终在线的远程访问，请参阅 [Tailscale](/gateway/tailscale)。
+
+---
+
+## 性能优化
+
+### 使用 USB SSD（显著提升）
+
+SD 卡速度慢且易磨损。USB SSD 会显著提升性能：
+
+```bash
+# 检查是否从 USB 启动
+lsblk
+```
+
+设置方法请参阅 [Pi USB boot guide](https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#usb-mass-storage-boot)。
+
+### 加快 CLI 启动速度（模块编译缓存）
+
+在性能较弱的 Pi 主机上，启用 Node 的模块编译缓存可以加快重复 CLI 运行速度：
+
+```bash
+grep -q 'NODE_COMPILE_CACHE=/var/tmp/quantumclaw-compile-cache' ~/.bashrc || cat >> ~/.bashrc <<'EOF' # pragma: allowlist secret
+export NODE_COMPILE_CACHE=/var/tmp/quantumclaw-compile-cache
+mkdir -p /var/tmp/quantumclaw-compile-cache
+export QUANTUMCLAW_NO_RESPAWN=1
+EOF
+source ~/.bashrc
+```
+
+说明：
+
+- `NODE_COMPILE_CACHE` 会加快后续运行（`status`、`health`、`--help`）。
+- `/var/tmp` 比 `/tmp` 更能在重启后保留内容。
+- `QUANTUMCLAW_NO_RESPAWN=1` 可避免 CLI 自重启带来的额外启动开销。
+- 第一次运行会预热缓存；之后的运行收益最大。
+
+### systemd 启动调优（可选）
+
+如果这台 Pi 主要运行 QuantumClaw，可以添加一个服务 drop-in，以减少重启抖动并保持稳定的启动环境：
+
+```bash
+sudo systemctl edit quantumclaw
+```
+
+```ini
+[Service]
+Environment=QUANTUMCLAW_NO_RESPAWN=1
+Environment=NODE_COMPILE_CACHE=/var/tmp/quantumclaw-compile-cache
+Restart=always
+RestartSec=2
+TimeoutStartSec=90
+```
+
+然后应用：
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl restart quantumclaw
+```
+
+如果可能，请将 QuantumClaw 状态/缓存放在 SSD 支持的存储上，以避免冷启动期间 SD 卡随机 I/O 成为瓶颈。
+
+关于 `Restart=` 策略如何帮助自动恢复：
+[systemd can automate service recovery](https://www.redhat.com/en/blog/systemd-automate-recovery)。
+
+### 减少内存占用
+
+```bash
+# 禁用 GPU 内存分配（无头）
+echo 'gpu_mem=16' | sudo tee -a /boot/config.txt
+
+# 如果不需要，禁用蓝牙
+sudo systemctl disable bluetooth
+```
+
+### 监控资源
+
+```bash
+# 检查内存
+free -h
+
+# 检查 CPU 温度
+vcgencmd measure_temp
+
+# 实时监控
+htop
+```
+
+---
+
+## ARM 特定说明
+
+### 二进制兼容性
+
+QuantumClaw 的大多数功能都可在 ARM64 上运行，但某些外部二进制文件可能需要 ARM 构建版本：
+
+| 工具               | ARM64 状态 | 说明                                |
+| ------------------ | ---------- | ----------------------------------- |
+| Node.js            | ✅         | 运行良好                            |
+| WhatsApp (Baileys) | ✅         | 纯 JS，无问题                       |
+| Telegram           | ✅         | 纯 JS，无问题                       |
+| gog (Gmail CLI)    | ⚠️         | 请检查是否有 ARM 发布版本           |
+| Chromium (browser) | ✅         | `sudo apt install chromium-browser` |
+
+如果某个 skill 失败，请检查其二进制文件是否有 ARM 构建版本。许多 Go/Rust 工具都有；有些则没有。
+
+### 32 位与 64 位
+
+**务必使用 64 位 OS。** Node.js 和许多现代工具都要求如此。使用以下命令检查：
+
+```bash
+uname -m
+# 应显示：aarch64（64 位），而不是 armv7l（32 位）
+```
+
+---
+
+## 推荐的模型设置
+
+由于 Pi 只是 Gateway 网关（模型在云中运行），请使用基于 API 的模型：
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "model": {
+        "primary": "anthropic/claude-sonnet-4-20250514",
+        "fallbacks": ["openai/gpt-4o-mini"]
+      }
+    }
+  }
+}
+```
+
+**不要尝试在 Pi 上运行本地 LLM** —— 即使是小模型也太慢了。让 Claude/GPT 负责主要计算工作。
+
+---
+
+## 开机自动启动
+
+设置向导会帮你配置这个，但你也可以这样验证：
+
+```bash
+# 检查服务是否已启用
+sudo systemctl is-enabled quantumclaw
+
+# 如果没有，则启用
+sudo systemctl enable quantumclaw
+
+# 开机启动
+sudo systemctl start quantumclaw
+```
+
+---
+
+## 故障排除
+
+### 内存不足（OOM）
+
+```bash
+# 检查内存
+free -h
+
+# 添加更多 swap（见第 5 步）
+# 或减少 Pi 上运行的服务
+```
+
+### 性能缓慢
+
+- 使用 USB SSD 替代 SD 卡
+- 禁用未使用的服务：`sudo systemctl disable cups bluetooth avahi-daemon`
+- 检查 CPU 限频：`vcgencmd get_throttled`（应返回 `0x0`）
+
+### 服务无法启动
+
+```bash
+# 检查日志
+journalctl -u quantumclaw --no-pager -n 100
+
+# 常见修复：重新构建
+cd ~/quantumclaw  # 如果使用的是可修改安装
+npm run build
+sudo systemctl restart quantumclaw
+```
+
+### ARM 二进制问题
+
+如果某个 skill 因 “exec format error” 失败：
+
+1. 检查该二进制文件是否有 ARM64 构建版本
+2. 尝试从源码构建
+3. 或使用支持 ARM 的 Docker 容器
+
+### Wi‑Fi 掉线
+
+对于通过 Wi‑Fi 运行的无头 Pi：
+
+```bash
+# 禁用 Wi‑Fi 省电
+sudo iwconfig wlan0 power off
+
+# 永久生效
+echo 'wireless-power off' | sudo tee -a /etc/network/interfaces
+```
+
+---
+
+## 成本对比
+
+| 方案            | 一次性成本 | 月成本   | 说明                     |
+| --------------- | ---------- | -------- | ------------------------ |
+| **Pi 4（2GB）** | ~$45       | $0       | + 电费（约 $5/年）       |
+| **Pi 4（4GB）** | ~$55       | $0       | 推荐                     |
+| **Pi 5（4GB）** | ~$60       | $0       | 最佳性能                 |
+| **Pi 5（8GB）** | ~$80       | $0       | 有些超配，但更有未来余量 |
+| DigitalOcean    | $0         | $6/月    | $72/年                   |
+| Hetzner         | $0         | €3.79/月 | 约 $50/年                |
+
+**回本周期：** 与云 VPS 相比，一台 Pi 大约 6–12 个月即可回本。
+
+---
+
+## 另请参阅
+
+- [Linux guide](/platforms/linux) — 通用 Linux 设置
+- [DigitalOcean guide](/platforms/digitalocean) — 云端替代方案
+- [Hetzner guide](/install/hetzner) — Docker 设置
+- [Tailscale](/gateway/tailscale) — 远程访问
+- [Nodes](/nodes) — 将你的笔记本电脑/手机与 Pi Gateway 网关配对

package/docs/zh-CN/platforms/windows.md

@@ -0,0 +1,247 @@
+---
+read_when:
+  - 在 Windows 上安装 QuantumClaw
+  - 查找 Windows 配套应用状态
+summary: Windows（WSL2）支持 + 配套应用状态
+title: Windows（WSL2）
+x-i18n:
+  generated_at: "2026-03-16T06:24:52Z"
+  model: gpt-5.4
+  provider: openai
+  source_hash: 2e905b129f34ac31e30d5767504233411b306b5985252f1a285e09f1ece19962
+  source_path: platforms/windows.md
+  workflow: 15
+---
+
+# Windows（WSL2）
+
+推荐在 Windows 上**通过 WSL2** 运行 QuantumClaw（推荐 Ubuntu）。CLI + Gateway 网关在 Linux 内运行，这能保持运行时一致，并使
+工具链兼容性高得多（Node/Bun/pnpm、Linux 二进制文件、Skills）。原生
+Windows 可能会更棘手。WSL2 可提供完整的 Linux 体验 —— 只需一条命令
+即可安装：`wsl --install`。
+
+原生 Windows 配套应用已在规划中。
+
+## 安装（WSL2）
+
+- [入门指南](/start/getting-started)（请在 WSL 内使用）
+- [安装与更新](/install/updating)
+- 官方 WSL2 指南（Microsoft）：[https://learn.microsoft.com/windows/wsl/install](https://learn.microsoft.com/windows/wsl/install)
+
+## 原生 Windows 状态
+
+原生 Windows CLI 流程正在改进，但 WSL2 仍然是推荐路径。
+
+当前在原生 Windows 上运行良好的内容：
+
+- 通过 `install.ps1` 使用网站安装器
+- 本地 CLI 用法，例如 `quantumclaw --version`、`quantumclaw doctor` 和 `quantumclaw plugins list --json`
+- 嵌入式 local-agent/provider 冒烟测试，例如：
+
+```powershell
+quantumclaw agent --local --agent main --thinking low -m "Reply with exactly WINDOWS-HATCH-OK."
+```
+
+当前注意事项：
+
+- 除非你传递 `--skip-health`，否则 `quantumclaw onboard --non-interactive` 仍然要求本地 Gateway 网关可访问
+- `quantumclaw onboard --non-interactive --install-daemon` 和 `quantumclaw gateway install` 会优先尝试 Windows Scheduled Tasks
+- 如果拒绝创建 Scheduled Task，QuantumClaw 会回退到每用户 Startup 文件夹登录项，并立即启动 Gateway 网关
+- 如果 `schtasks` 本身卡住或停止响应，QuantumClaw 现在会快速中止该路径并回退，而不是无限挂起
+- 在可用时仍优先使用 Scheduled Tasks，因为它们能提供更好的 supervisor 状态
+
+如果你只想使用原生 CLI，而不安装 Gateway 网关服务，可使用以下任一方式：
+
+```powershell
+quantumclaw onboard --non-interactive --skip-health
+quantumclaw gateway run
+```
+
+如果你确实想在原生 Windows 上使用受管启动：
+
+```powershell
+quantumclaw gateway install
+quantumclaw gateway status --json
+```
+
+如果无法创建 Scheduled Task，回退服务模式仍会通过当前用户的 Startup 文件夹在登录后自动启动。
+
+## Gateway 网关
+
+- [Gateway 网关运行手册](/gateway)
+- [配置](/gateway/configuration)
+
+## Gateway 网关服务安装（CLI）
+
+在 WSL2 内：
+
+```
+quantumclaw onboard --install-daemon
+```
+
+或者：
+
+```
+quantumclaw gateway install
+```
+
+或者：
+
+```
+quantumclaw configure
+```
+
+出现提示时，选择 **Gateway 服务**。
+
+修复/迁移：
+
+```
+quantumclaw doctor
+```
+
+## 在 Windows 登录前自动启动 Gateway 网关
+
+对于无头设置，请确保完整的启动链即使在无人登录
+Windows 时也能运行。
+
+### 1）在未登录时保持用户服务运行
+
+在 WSL 内：
+
+```bash
+sudo loginctl enable-linger "$(whoami)"
+```
+
+### 2）安装 QuantumClaw Gateway 网关用户服务
+
+在 WSL 内：
+
+```bash
+quantumclaw gateway install
+```
+
+### 3）在 Windows 启动时自动启动 WSL
+
+以管理员身份打开 PowerShell：
+
+```powershell
+schtasks /create /tn "WSL Boot" /tr "wsl.exe -d Ubuntu --exec /bin/true" /sc onstart /ru SYSTEM
+```
+
+将 `Ubuntu` 替换为以下命令输出中的发行版名称：
+
+```powershell
+wsl --list --verbose
+```
+
+### 验证启动链
+
+重启后（在 Windows 登录前），在 WSL 中检查：
+
+```bash
+systemctl --user is-enabled quantumclaw-gateway
+systemctl --user status quantumclaw-gateway --no-pager
+```
+
+## 高级：通过局域网暴露 WSL 服务（portproxy）
+
+WSL 有自己的虚拟网络。如果另一台机器需要访问
+**在 WSL 内运行**的服务（SSH、本地 TTS 服务器或 Gateway 网关），你必须
+将 Windows 端口转发到当前的 WSL IP。WSL IP 会在重启后变化，
+因此你可能需要刷新转发规则。
+
+示例（**以管理员身份**打开 PowerShell）：
+
+```powershell
+$Distro = "Ubuntu-24.04"
+$ListenPort = 2222
+$TargetPort = 22
+
+$WslIp = (wsl -d $Distro -- hostname -I).Trim().Split(" ")[0]
+if (-not $WslIp) { throw "WSL IP not found." }
+
+netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=$ListenPort `
+  connectaddress=$WslIp connectport=$TargetPort
+```
+
+允许该端口通过 Windows 防火墙（一次性）：
+
+```powershell
+New-NetFirewallRule -DisplayName "WSL SSH $ListenPort" -Direction Inbound `
+  -Protocol TCP -LocalPort $ListenPort -Action Allow
+```
+
+在 WSL 重启后刷新 portproxy：
+
+```powershell
+netsh interface portproxy delete v4tov4 listenport=$ListenPort listenaddress=0.0.0.0 | Out-Null
+netsh interface portproxy add v4tov4 listenport=$ListenPort listenaddress=0.0.0.0 `
+  connectaddress=$WslIp connectport=$TargetPort | Out-Null
+```
+
+说明：
+
+- 来自另一台机器的 SSH 应指向**Windows 主机 IP**（例如：`ssh user@windows-host -p 2222`）。
+- 远程节点必须指向**可访问的** Gateway 网关 URL（而不是 `127.0.0.1`）；请使用
+  `quantumclaw status --all` 进行确认。
+- 使用 `listenaddress=0.0.0.0` 可供局域网访问；`127.0.0.1` 则仅限本地。
+- 如果你希望自动执行此操作，请注册一个 Scheduled Task，在登录时运行刷新
+  步骤。
+
+## 分步 WSL2 安装
+
+### 1）安装 WSL2 + Ubuntu
+
+打开 PowerShell（管理员）：
+
+```powershell
+wsl --install
+# 或显式选择一个发行版：
+wsl --list --online
+wsl --install -d Ubuntu-24.04
+```
+
+如果 Windows 提示，请重启。
+
+### 2）启用 systemd（Gateway 网关安装所必需）
+
+在你的 WSL 终端中：
+
+```bash
+sudo tee /etc/wsl.conf >/dev/null <<'EOF'
+[boot]
+systemd=true
+EOF
+```
+
+然后在 PowerShell 中运行：
+
+```powershell
+wsl --shutdown
+```
+
+重新打开 Ubuntu，然后验证：
+
+```bash
+systemctl --user status
+```
+
+### 3）安装 QuantumClaw（在 WSL 内）
+
+在 WSL 内按照 Linux 入门指南流程操作：
+
+```bash
+git clone https://github.com/quantumclaw/quantumclaw.git
+cd quantumclaw
+pnpm install
+pnpm ui:build # 首次运行时会自动安装 UI 依赖
+pnpm build
+quantumclaw onboard
+```
+
+完整指南：[入门指南](/start/getting-started)
+
+## Windows 配套应用
+
+我们还没有 Windows 配套应用。如果你想推动这件事发生，欢迎
+贡献。