@gguf/claw 2026.2.1 → 2026.2.3

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

@@ -0,0 +1,310 @@
+---
+read_when:
+  - 在 Oracle Cloud 上部署 OpenClaw
+  - 寻找低成本 VPS 托管方案来运行 OpenClaw
+  - 希望在小型服务器上全天候运行 OpenClaw
+summary: 在 Oracle Cloud（Always Free ARM）上运行 OpenClaw
+title: Oracle Cloud
+x-i18n:
+  generated_at: "2026-02-01T21:34:35Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: d3cc337b40ea512b5756ac15ec4341fecad417ede75f717fea3035678c7c6697
+  source_path: platforms/oracle.md
+  workflow: 15
+---
+
+# 在 Oracle Cloud (OCI) 上运行 OpenClaw
+
+## 目标
+
+在 Oracle Cloud 的 **Always Free** ARM 层级上运行持久化的 OpenClaw Gateway网关。
+
+Oracle 的免费层级非常适合运行 OpenClaw（特别是如果你已有 OCI 账户），但也存在一些权衡：
+
+- ARM 架构（大多数东西都能运行，但某些二进制文件可能仅支持 x86）
+- 容量和注册流程可能不太稳定
+
+## 费用对比（2026）
+
+| 提供商       | 方案            | 配置                  | 月费用 | 备注               |
+| ------------ | --------------- | --------------------- | ------ | ------------------ |
+| Oracle Cloud | Always Free ARM | 最高 4 OCPU, 24GB RAM | $0     | ARM，容量有限      |
+| Hetzner      | CX22            | 2 vCPU, 4GB RAM       | ~ $4   | 最便宜的付费选项   |
+| DigitalOcean | Basic           | 1 vCPU, 1GB RAM       | $6     | 界面简洁，文档完善 |
+| Vultr        | Cloud Compute   | 1 vCPU, 1GB RAM       | $6     | 机房节点多         |
+| Linode       | Nanode          | 1 vCPU, 1GB RAM       | $5     | 现为 Akamai 旗下   |
+
+---
+
+## 前提条件
+
+- Oracle Cloud 账户（[注册](https://www.oracle.com/cloud/free/)）— 如果遇到问题请参阅[社区注册指南](https://gist.github.com/rssnyder/51e3cfedd730e7dd5f4a816143b25dbd)
+- Tailscale 账户（在 [tailscale.com](https://tailscale.com) 免费注册）
+- 约 30 分钟
+
+## 1) 创建 OCI 实例
+
+1. 登录 [Oracle Cloud 控制台](https://cloud.oracle.com/)
+2. 导航至 **Compute → Instances → Create Instance**
+3. 配置：
+   - **Name:** `openclaw`
+   - **Image:** Ubuntu 24.04 (aarch64)
+   - **Shape:** `VM.Standard.A1.Flex` (Ampere ARM)
+   - **OCPUs:** 2（最高 4）
+   - **Memory:** 12 GB（最高 24 GB）
+   - **Boot volume:** 50 GB（免费额度最高 200 GB）
+   - **SSH key:** 添加你的公钥
+4. 点击 **Create**
+5. 记下公共 IP 地址
+
+**提示：** 如果实例创建失败并提示 "Out of capacity"，请尝试其他可用性域或稍后重试。免费层级容量有限。
+
+## 2) 连接并更新
+
+```bash
+# 通过公共 IP 连接
+ssh ubuntu@YOUR_PUBLIC_IP
+
+# 更新系统
+sudo apt update && sudo apt upgrade -y
+sudo apt install -y build-essential
+```
+
+**注意：** ARM 架构下编译某些依赖需要 `build-essential`。
+
+## 3) 配置用户和主机名
+
+```bash
+# 设置主机名
+sudo hostnamectl set-hostname openclaw
+
+# 为 ubuntu 用户设置密码
+sudo passwd ubuntu
+
+# 启用 lingering（注销后保持用户服务运行）
+sudo loginctl enable-linger ubuntu
+```
+
+## 4) 安装 Tailscale
+
+```bash
+curl -fsSL https://tailscale.com/install.sh | sh
+sudo tailscale up --ssh --hostname=openclaw
+```
+
+这将启用 Tailscale SSH，让你可以从 tailnet 上的任何设备通过 `ssh openclaw` 连接，无需公共 IP。
+
+验证：
+
+```bash
+tailscale status
+```
+
+**从现在开始，通过 Tailscale 连接：** `ssh ubuntu@openclaw`（或使用 Tailscale IP）。
+
+## 5) 安装 OpenClaw
+
+```bash
+curl -fsSL https://openclaw.ai/install.sh | bash
+source ~/.bashrc
+```
+
+当提示 "How do you want to hatch your bot?" 时，选择 **"Do this later"**。
+
+> 注意：如果遇到 ARM 原生构建问题，请先安装系统包（例如 `sudo apt install -y build-essential`），再考虑使用 Homebrew。
+
+## 6) 配置 Gateway网关（local loopback 绑定 + 令牌认证）并启用 Tailscale Serve
+
+默认使用令牌认证。这种方式可预测，且无需在控制 UI 中设置任何"不安全认证"标志。
+
+```bash
+# 将 Gateway网关限制在虚拟机本地
+openclaw config set gateway.bind loopback
+
+# 为 Gateway网关 + 控制 UI 启用认证
+openclaw config set gateway.auth.mode token
+openclaw doctor --generate-gateway-token
+
+# 通过 Tailscale Serve 暴露（HTTPS + tailnet 访问）
+openclaw config set gateway.tailscale.mode serve
+openclaw config set gateway.trustedProxies '["127.0.0.1"]'
+
+systemctl --user restart openclaw-gateway
+```
+
+## 7) 验证
+
+```bash
+# 检查版本
+openclaw --version
+
+# 检查守护进程状态
+systemctl --user status openclaw-gateway
+
+# 检查 Tailscale Serve
+tailscale serve status
+
+# 测试本地响应
+curl http://localhost:18789
+```
+
+## 8) 锁定 VCN 安全规则
+
+一切正常运行后，锁定 VCN 以阻止除 Tailscale 外的所有流量。OCI 的虚拟云网络在网络边缘充当防火墙——流量在到达实例之前就被拦截。
+
+1. 在 OCI 控制台中进入 **Networking → Virtual Cloud Networks**
+2. 点击你的 VCN → **Security Lists** → Default Security List
+3. **删除**所有入站规则，仅保留：
+   - `0.0.0.0/0 UDP 41641`（Tailscale）
+4. 保留默认出站规则（允许所有出站流量）
+
+这将在网络边缘阻止 22 端口 SSH、HTTP、HTTPS 及其他所有流量。从此以后，你只能通过 Tailscale 连接。
+
+---
+
+## 访问控制 UI
+
+从 Tailscale 网络上的任意设备访问：
+
+```
+https://openclaw.<tailnet-name>.ts.net/
+```
+
+将 `<tailnet-name>` 替换为你的 tailnet 名称（可在 `tailscale status` 中查看）。
+
+无需 SSH 隧道。Tailscale 提供：
+
+- HTTPS 加密（自动证书）
+- 通过 Tailscale 身份进行认证
+- 从 tailnet 上的任何设备访问（笔记本电脑、手机等）
+
+---
+
+## 安全性：VCN + Tailscale（推荐基线）
+
+锁定 VCN（仅开放 UDP 41641）并将 Gateway网关绑定到 local loopback 后，你将获得强大的纵深防御：公共流量在网络边缘被阻止，管理访问通过 tailnet 进行。
+
+这种配置通常不再*需要*额外的主机防火墙规则来阻止全网 SSH 暴力破解——但你仍应保持操作系统更新、运行 `openclaw security audit`，并确认没有意外监听公共接口。
+
+### 已受保护的内容
+
+| 传统步骤        | 是否需要？ | 原因                                               |
+| --------------- | ---------- | -------------------------------------------------- |
+| UFW 防火墙      | 否         | VCN 在流量到达实例之前就已拦截                     |
+| fail2ban        | 否         | VCN 阻止了 22 端口，不存在暴力破解                 |
+| sshd 加固       | 否         | Tailscale SSH 不使用 sshd                          |
+| 禁用 root 登录  | 否         | Tailscale 使用 Tailscale 身份认证，而非系统用户    |
+| 仅密钥 SSH 认证 | 否         | Tailscale 通过 tailnet 进行认证                    |
+| IPv6 加固       | 通常不需要 | 取决于你的 VCN/子网设置；请验证实际分配/暴露的内容 |
+
+### 仍然建议执行
+
+- **凭据权限：** `chmod 700 ~/.openclaw`
+- **安全审计：** `openclaw security audit`
+- **系统更新：** 定期运行 `sudo apt update && sudo apt upgrade`
+- **监控 Tailscale：** 在 [Tailscale 管理控制台](https://login.tailscale.com/admin) 中检查设备
+
+### 验证安全状态
+
+```bash
+# 确认没有公共端口在监听
+sudo ss -tlnp | grep -v '127.0.0.1\|::1'
+
+# 验证 Tailscale SSH 是否激活
+tailscale status | grep -q 'offers: ssh' && echo "Tailscale SSH active"
+
+# 可选：完全禁用 sshd
+sudo systemctl disable --now ssh
+```
+
+---
+
+## 备选方案：SSH 隧道
+
+如果 Tailscale Serve 无法正常工作，可使用 SSH 隧道：
+
+```bash
+# 从本地机器（通过 Tailscale）
+ssh -L 18789:127.0.0.1:18789 ubuntu@openclaw
+```
+
+然后打开 `http://localhost:18789`。
+
+---
+
+## 故障排除
+
+### 实例创建失败（"Out of capacity"）
+
+免费层级 ARM 实例非常热门。请尝试：
+
+- 切换不同的可用性域
+- 在非高峰时段重试（清晨）
+- 选择配置时使用 "Always Free" 筛选器
+
+### Tailscale 无法连接
+
+```bash
+# 检查状态
+sudo tailscale status
+
+# 重新认证
+sudo tailscale up --ssh --hostname=openclaw --reset
+```
+
+### Gateway网关无法启动
+
+```bash
+openclaw gateway status
+openclaw doctor --non-interactive
+journalctl --user -u openclaw-gateway -n 50
+```
+
+### 无法访问控制 UI
+
+```bash
+# 验证 Tailscale Serve 是否在运行
+tailscale serve status
+
+# 检查 Gateway网关是否在监听
+curl http://localhost:18789
+
+# 需要时重启
+systemctl --user restart openclaw-gateway
+```
+
+### ARM 二进制文件问题
+
+某些工具可能没有 ARM 构建版本。检查：
+
+```bash
+uname -m  # 应显示 aarch64
+```
+
+大多数 npm 包都能正常工作。对于二进制文件，请查找 `linux-arm64` 或 `aarch64` 版本。
+
+---
+
+## 持久化
+
+所有状态保存在：
+
+- `~/.openclaw/` — 配置、凭据、会话数据
+- `~/.openclaw/workspace/` — 工作区（SOUL.md、记忆、产物）
+
+定期备份：
+
+```bash
+tar -czvf openclaw-backup.tar.gz ~/.openclaw ~/.openclaw/workspace
+```
+
+---
+
+## 另请参阅
+
+- [Gateway网关远程访问](/gateway/remote) — 其他远程访问模式
+- [Tailscale 集成](/gateway/tailscale) — 完整 Tailscale 文档
+- [Gateway网关配置](/gateway/configuration) — 所有配置选项
+- [DigitalOcean 指南](/platforms/digitalocean) — 付费但注册更简单的选择
+- [Hetzner 指南](/platforms/hetzner) — 基于 Docker 的替代方案

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

@@ -0,0 +1,365 @@
+---
+read_when:
+  - 在 Raspberry Pi 上设置 OpenClaw
+  - 在 ARM 设备上运行 OpenClaw
+  - 搭建低成本的全天候个人 AI
+summary: 在 Raspberry Pi 上运行 OpenClaw（低成本自托管方案）
+title: Raspberry Pi
+x-i18n:
+  generated_at: "2026-02-01T21:34:34Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 6741eaf0115a4fa0efd6599a99e0526a20ceb30eda1d9b04cba9dd5dec84bee2
+  source_path: platforms/raspberry-pi.md
+  workflow: 15
+---
+
+# 在 Raspberry Pi 上运行 OpenClaw
+
+## 目标
+
+在 Raspberry Pi 上运行一个持久的、全天候在线的 OpenClaw Gateway网关，**一次性费用约 $35-80**（无月费）。
+
+适用场景：
+
+- 24/7 个人 AI 助手
+- 家庭自动化中枢
+- 低功耗、随时可用的 Telegram/WhatsApp 机器人
+
+## 硬件要求
+
+| Pi 型号         | 内存    | 可用？  | 备注                           |
+| --------------- | ------- | ------- | ------------------------------ |
+| **Pi 5**        | 4GB/8GB | ✅ 最佳 | 速度最快，推荐                 |
+| **Pi 4**        | 4GB     | ✅ 良好 | 大多数用户的最佳性价比         |
+| **Pi 4**        | 2GB     | ✅ 可用 | 可运行，需添加交换空间         |
+| **Pi 4**        | 1GB     | ⚠️ 紧张 | 需交换空间和最小化配置才可运行 |
+| **Pi 3B+**      | 1GB     | ⚠️ 缓慢 | 可运行但较卡顿                 |
+| **Pi Zero 2 W** | 512MB   | ❌      | 不推荐                         |
+
+**最低配置：** 1GB 内存，1 核，500MB 磁盘空间
+**推荐配置：** 2GB+ 内存，64 位系统，16GB+ SD 卡（或 USB SSD）
+
+## 你需要准备
+
+- Raspberry Pi 4 或 5（推荐 2GB+ 内存）
+- MicroSD 卡（16GB+）或 USB SSD（性能更好）
+- 电源适配器（推荐官方 Pi 电源）
+- 网络连接（以太网或 WiFi）
+- 约 30 分钟时间
+
+## 1) 刷写系统
+
+使用 **Raspberry Pi OS Lite (64-bit)** — 无桌面的无头服务器无需桌面环境。
+
+1. 下载 [Raspberry Pi Imager](https://www.raspberrypi.com/software/)
+2. 选择系统：**Raspberry Pi OS Lite (64-bit)**
+3. 点击齿轮图标（⚙️）预配置：
+   - 设置主机名：`gateway-host`
+   - 启用 SSH
+   - 设置用户名/密码
+   - 配置 WiFi（如果不使用以太网）
+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
+
+# 设置时区（对定时任务/提醒很重要）
+sudo timedatectl set-timezone America/Chicago  # 改为你的时区
+```
+
+## 4) 安装 Node.js 22 (ARM64)
+
+```bash
+# 通过 NodeSource 安装 Node.js
+curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
+sudo apt install -y nodejs
+
+# 验证
+node --version  # 应显示 v22.x.x
+npm --version
+```
+
+## 5) 添加交换空间（2GB 及以下内存必做）
+
+交换空间可防止内存不足导致的崩溃：
+
+```bash
+# 创建 2GB 交换文件
+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) 安装 OpenClaw
+
+### 方案 A：标准安装（推荐）
+
+```bash
+curl -fsSL https://openclaw.ai/install.sh | bash
+```
+
+### 方案 B：可修改安装（适合折腾）
+
+```bash
+git clone https://github.com/openclaw/openclaw.git
+cd openclaw
+npm install
+npm run build
+npm link
+```
+
+可修改安装让你可以直接访问日志和代码 — 对调试 ARM 特定问题很有用。
+
+## 7) 运行新手引导
+
+```bash
+openclaw onboard --install-daemon
+```
+
+按照向导操作：
+
+1. **Gateway网关模式：** 本地
+2. **认证：** 推荐使用 API 密钥（OAuth 在无头 Pi 上可能不太稳定）
+3. **渠道：** Telegram 最容易上手
+4. **守护进程：** 是（systemd）
+
+## 8) 验证安装
+
+```bash
+# 检查状态
+openclaw status
+
+# 检查服务
+sudo systemctl status openclaw
+
+# 查看日志
+journalctl -u openclaw -f
+```
+
+## 9) 访问仪表盘
+
+由于 Pi 是无头模式，使用 SSH 隧道：
+
+```bash
+# 从你的笔记本/台式机
+ssh -L 18789:localhost:18789 user@gateway-host
+
+# 然后在浏览器中打开
+open http://localhost:18789
+```
+
+或使用 Tailscale 实现全天候访问：
+
+```bash
+# 在 Pi 上
+curl -fsSL https://tailscale.com/install.sh | sh
+sudo tailscale up
+
+# 更新配置
+openclaw config set gateway.bind tailnet
+sudo systemctl restart openclaw
+```
+
+---
+
+## 性能优化
+
+### 使用 USB SSD（显著提升）
+
+SD 卡速度慢且易损耗。USB SSD 能大幅提升性能：
+
+```bash
+# 检查是否从 USB 启动
+lsblk
+```
+
+设置方法请参阅 [Pi USB 启动指南](https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#usb-mass-storage-boot)。
+
+### 减少内存占用
+
+```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 特定说明
+
+### 二进制兼容性
+
+大多数 OpenClaw 功能在 ARM64 上正常工作，但部分外部二进制文件可能需要 ARM 构建版本：
+
+| 工具               | ARM64 状态 | 备注                                |
+| ------------------ | ---------- | ----------------------------------- |
+| Node.js            | ✅         | 运行良好                            |
+| WhatsApp (Baileys) | ✅         | 纯 JS，无问题                       |
+| Telegram           | ✅         | 纯 JS，无问题                       |
+| gog (Gmail CLI)    | ⚠️         | 请检查是否有 ARM 版本               |
+| Chromium (browser) | ✅         | `sudo apt install chromium-browser` |
+
+如果某个 Skills 运行失败，请检查其二进制文件是否有 ARM 构建版本。大多数 Go/Rust 工具有；部分没有。
+
+### 32 位 vs 64 位
+
+**务必使用 64 位系统。** Node.js 和许多现代工具都需要 64 位。检查方法：
+
+```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 上运行本地大语言模型** — 即使是小模型也太慢。让 Claude/GPT 来完成繁重的工作。
+
+---
+
+## 开机自启动
+
+新手引导向导会自动设置，但可以验证一下：
+
+```bash
+# 检查服务是否已启用
+sudo systemctl is-enabled openclaw
+
+# 如未启用则启用
+sudo systemctl enable openclaw
+
+# 开机启动
+sudo systemctl start openclaw
+```
+
+---
+
+## 故障排除
+
+### 内存不足 (OOM)
+
+```bash
+# 检查内存
+free -h
+
+# 添加更多交换空间（参见步骤 5）
+# 或减少 Pi 上运行的服务
+```
+
+### 性能缓慢
+
+- 使用 USB SSD 替代 SD 卡
+- 禁用未使用的服务：`sudo systemctl disable cups bluetooth avahi-daemon`
+- 检查 CPU 降频：`vcgencmd get_throttled`（应返回 `0x0`）
+
+### 服务无法启动
+
+```bash
+# 检查日志
+journalctl -u openclaw --no-pager -n 100
+
+# 常见修复方法：重新构建
+cd ~/openclaw  # 如果使用可修改安装
+npm run build
+sudo systemctl restart openclaw
+```
+
+### ARM 二进制问题
+
+如果某个 Skills 报错 "exec format error"：
+
+1. 检查该二进制文件是否有 ARM64 构建版本
+2. 尝试从源码编译
+3. 或使用支持 ARM 的 Docker 容器
+
+### WiFi 断连
+
+对于使用 WiFi 的无头 Pi：
+
+```bash
+# 禁用 WiFi 电源管理
+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 指南](/platforms/linux) — 通用 Linux 设置
+- [DigitalOcean 指南](/platforms/digitalocean) — 云端替代方案
+- [Hetzner 指南](/platforms/hetzner) — Docker 设置
+- [Tailscale](/gateway/tailscale) — 远程访问
+- [节点](/nodes) — 将你的笔记本/手机与 Pi Gateway网关配对