@captain-app/openclaw 2026.2.4

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

@@ -0,0 +1,310 @@
+---
+read_when:
+  - 在 Oracle Cloud 上设置 OpenClaw
+  - 寻找 OpenClaw 的低成本 VPS 托管
+  - 想要在小型服务器上 24/7 运行 OpenClaw
+summary: 在 Oracle Cloud 上运行 OpenClaw（Always Free ARM）
+title: Oracle Cloud
+x-i18n:
+  generated_at: "2026-02-03T07:53:25Z"
+  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      | 易用的 UI，文档完善  |
+| 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 Console](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
+```
+
+**注意：** `build-essential` 是某些依赖项 ARM 编译所必需的。
+
+## 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 原生构建问题，在使用 Homebrew 之前先从系统包开始（例如 `sudo apt install -y build-essential`）。
+
+## 6) 配置 Gateway 网关（loopback + 令牌认证）并启用 Tailscale Serve
+
+使用令牌认证作为默认值。它是可预测的，避免需要任何"不安全认证"的控制 UI 标志。
+
+```bash
+# 在 VM 上保持 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 Console 中转到 **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 网关绑定到 loopback，你获得了强大的纵深防御：公共流量在网络边缘被阻止，管理访问通过你的 tailnet 进行。
+
+此设置通常消除了纯粹为了阻止互联网范围的 SSH 暴力破解而需要额外的基于主机的防火墙规则的*需求*——但你仍应保持操作系统更新，运行 `openclaw security audit`，并验证你没有意外地在公共接口上监听。
+
+### 已经受保护的内容
+
+| 传统步骤        | 是否需要？ | 原因                                             |
+| --------------- | ---------- | ------------------------------------------------ |
+| UFW 防火墙      | 否         | VCN 在流量到达实例之前就阻止了                   |
+| fail2ban        | 否         | 如果端口 22 在 VCN 被阻止则无暴力破解            |
+| 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 实例很受欢迎。尝试：
+
+- 不同的可用性域
+- 在非高峰时段（清晨）重试
+- 选择 shape 时使用"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-03T07:53:30Z"
+  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
+
+# 设置时区（对 cron/提醒很重要）
+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 网关模式：** Local
+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` |
+
+如果某个 skill 失败，检查其二进制文件是否有 ARM 构建。许多 Go/Rust 工具有；有些没有。
+
+### 32 位 vs 64 位
+
+**始终使用 64 位系统。** 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 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 二进制问题
+
+如果某个 skill 失败并显示"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 网关配对