mirror of
https://github.com/openclaw/openclaw.git
synced 2026-05-03 05:28:23 +00:00
Docs: add zh-CN translations
This commit is contained in:
Josh Palmer
155
docs/zh-CN/platforms/android.md
Normal file
155
docs/zh-CN/platforms/android.md
Normal file
@@ -0,0 +1,155 @@
|
||||
---
|
||||
read_when:
|
||||
- 配对或重新连接 Android 节点
|
||||
- 调试 Android Gateway 发现或认证问题
|
||||
- 验证跨客户端的聊天历史一致性
|
||||
summary: Android 应用（节点）：连接运维手册 + Canvas/聊天/相机
|
||||
title: Android 应用
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T21:19:33Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: 9cd02f12065ce2bc483379c9afd7537489d9076094f4a412cf9f21ccc47f0e38
|
||||
source_path: platforms/android.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Android 应用（节点）
|
||||
|
||||
## 支持概览
|
||||
|
||||
- 角色：伴侣节点应用（Android 不托管 Gateway）。
|
||||
- 需要 Gateway：是（在 macOS、Linux 或通过 WSL2 的 Windows 上运行）。
|
||||
- 安装：[快速入门](/start/getting-started) + [配对](/gateway/pairing)。
|
||||
- Gateway：[运维手册](/gateway) + [配置](/gateway/configuration)。
|
||||
- 协议：[Gateway 协议](/gateway/protocol)（节点 + 控制平面）。
|
||||
|
||||
## 系统控制
|
||||
|
||||
系统控制（launchd/systemd）在 Gateway 主机上。参见 [Gateway](/gateway)。
|
||||
|
||||
## 连接运维手册
|
||||
|
||||
Android 节点应用 ⇄（mDNS/NSD + WebSocket）⇄ **Gateway**
|
||||
|
||||
Android 直接连接到 Gateway WebSocket（默认 `ws://<host>:18789`）并使用 Gateway 管理的配对。
|
||||
|
||||
### 前提条件
|
||||
|
||||
- 你可以在"主"机器上运行 Gateway。
|
||||
- Android 设备/模拟器可以访问 Gateway WebSocket：
|
||||
- 同一局域网且支持 mDNS/NSD，**或**
|
||||
- 同一 Tailscale tailnet，使用 Wide-Area Bonjour / 单播 DNS-SD（见下文），**或**
|
||||
- 手动指定 Gateway 主机/端口（备用方案）
|
||||
- 你可以在 Gateway 机器上（或通过 SSH）运行 CLI（`openclaw`）。
|
||||
|
||||
### 1）启动 Gateway
|
||||
|
||||
```bash
|
||||
openclaw gateway --port 18789 --verbose
|
||||
```
|
||||
|
||||
在日志中确认你看到类似内容：
|
||||
|
||||
- `listening on ws://0.0.0.0:18789`
|
||||
|
||||
对于仅 tailnet 的设置（推荐用于 Vienna ⇄ London），将 Gateway 绑定到 tailnet IP：
|
||||
|
||||
- 在 Gateway 主机的 `~/.openclaw/openclaw.json` 中设置 `gateway.bind: "tailnet"`。
|
||||
- 重启 Gateway / macOS 菜单栏应用。
|
||||
|
||||
### 2）验证发现（可选）
|
||||
|
||||
在 Gateway 机器上：
|
||||
|
||||
```bash
|
||||
dns-sd -B _openclaw-gw._tcp local.
|
||||
```
|
||||
|
||||
更多调试说明：[Bonjour](/gateway/bonjour)。
|
||||
|
||||
#### Tailnet（Vienna ⇄ London）通过单播 DNS-SD 发现
|
||||
|
||||
Android NSD/mDNS 发现无法跨网络工作。如果你的 Android 节点和 Gateway 在不同网络上但通过 Tailscale 连接，请改用 Wide-Area Bonjour / 单播 DNS-SD：
|
||||
|
||||
1. 在 Gateway 主机上设置 DNS-SD 区域（示例 `openclaw.internal.`）并发布 `_openclaw-gw._tcp` 记录。
|
||||
2. 配置 Tailscale split DNS，将你选择的域名指向该 DNS 服务器。
|
||||
|
||||
详情和示例 CoreDNS 配置：[Bonjour](/gateway/bonjour)。
|
||||
|
||||
### 3）从 Android 连接
|
||||
|
||||
在 Android 应用中：
|
||||
|
||||
- 应用通过**前台服务**（持久通知）保持 Gateway 连接活跃。
|
||||
- 打开**设置**。
|
||||
- 在**已发现的 Gateway** 下，选择你的 Gateway 并点击**连接**。
|
||||
- 如果 mDNS 被阻止，使用**高级 → 手动 Gateway**（主机 + 端口）并点击**连接（手动）**。
|
||||
|
||||
首次成功配对后，Android 会在启动时自动重连：
|
||||
|
||||
- 手动端点（如已启用），否则
|
||||
- 上次发现的 Gateway（尽力而为）。
|
||||
|
||||
### 4）审批配对（CLI）
|
||||
|
||||
在 Gateway 机器上：
|
||||
|
||||
```bash
|
||||
openclaw nodes pending
|
||||
openclaw nodes approve <requestId>
|
||||
```
|
||||
|
||||
配对详情：[Gateway 配对](/gateway/pairing)。
|
||||
|
||||
### 5）验证节点已连接
|
||||
|
||||
- 通过节点状态：
|
||||
```bash
|
||||
openclaw nodes status
|
||||
```
|
||||
- 通过 Gateway：
|
||||
```bash
|
||||
openclaw gateway call node.list --params "{}"
|
||||
```
|
||||
|
||||
### 6）聊天 + 历史记录
|
||||
|
||||
Android 节点的聊天界面使用 Gateway 的**主会话键**（`main`），因此历史记录和回复与 WebChat 及其他客户端共享：
|
||||
|
||||
- 历史记录：`chat.history`
|
||||
- 发送：`chat.send`
|
||||
- 推送更新（尽力而为）：`chat.subscribe` → `event:"chat"`
|
||||
|
||||
### 7）Canvas + 相机
|
||||
|
||||
#### Gateway Canvas 主机（推荐用于 Web 内容）
|
||||
|
||||
如果你希望节点显示智能体可以在磁盘上编辑的真实 HTML/CSS/JS，请将节点指向 Gateway canvas 主机。
|
||||
|
||||
注意：节点使用 `canvasHost.port`（默认 `18793`）上的独立 canvas 主机。
|
||||
|
||||
1. 在 Gateway 主机上创建 `~/.openclaw/workspace/canvas/index.html`。
|
||||
|
||||
2. 将节点导航到该地址（局域网）：
|
||||
|
||||
```bash
|
||||
openclaw nodes invoke --node "<Android Node>" --command canvas.navigate --params '{"url":"http://<gateway-hostname>.local:18793/__openclaw__/canvas/"}'
|
||||
```
|
||||
|
||||
Tailnet（可选）：如果两台设备都在 Tailscale 上，使用 MagicDNS 名称或 tailnet IP 替代 `.local`，例如 `http://<gateway-magicdns>:18793/__openclaw__/canvas/`。
|
||||
|
||||
该服务器会向 HTML 注入实时重载客户端，并在文件变更时重新加载。
|
||||
A2UI 主机位于 `http://<gateway-host>:18793/__openclaw__/a2ui/`。
|
||||
|
||||
Canvas 命令（仅前台）：
|
||||
|
||||
- `canvas.eval`、`canvas.snapshot`、`canvas.navigate`（使用 `{"url":""}` 或 `{"url":"/"}` 返回默认脚手架）。`canvas.snapshot` 返回 `{ format, base64 }`（默认 `format="jpeg"`）。
|
||||
- A2UI：`canvas.a2ui.push`、`canvas.a2ui.reset`（`canvas.a2ui.pushJSONL` 旧版别名）
|
||||
|
||||
相机命令（仅前台；需权限）：
|
||||
|
||||
- `camera.snap`（jpg）
|
||||
- `camera.clip`（mp4）
|
||||
|
||||
参见[相机节点](/nodes/camera)了解参数和 CLI 辅助工具。
|
||||
269
docs/zh-CN/platforms/digitalocean.md
Normal file
269
docs/zh-CN/platforms/digitalocean.md
Normal file
@@ -0,0 +1,269 @@
|
||||
---
|
||||
read_when:
|
||||
- 在 DigitalOcean 上设置 OpenClaw
|
||||
- 寻找便宜的 VPS 托管来运行 OpenClaw
|
||||
summary: 在 DigitalOcean 上运行 OpenClaw（简单的付费 VPS 方案）
|
||||
title: DigitalOcean
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T21:20:02Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: d60559b8751da37413e5364e83c88254b476b2283386a0b07b2ca6b4e16157fc
|
||||
source_path: platforms/digitalocean.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 在 DigitalOcean 上运行 OpenClaw
|
||||
|
||||
## 目标
|
||||
|
||||
在 DigitalOcean 上运行持久化的 OpenClaw Gateway，费用为**每月 $6**（预留定价为每月 $4）。
|
||||
|
||||
如果你想要每月 $0 的方案且不介意 ARM + 特定提供商的设置，请参阅 [Oracle Cloud 指南](/platforms/oracle)。
|
||||
|
||||
## 费用对比（2026）
|
||||
|
||||
| 提供商 | 方案 | 规格 | 月费 | 备注 |
|
||||
| ------------ | --------------- | --------------------- | ----------- | -------------------------- |
|
||||
| Oracle Cloud | Always Free ARM | 最高 4 OCPU, 24GB RAM | $0 | ARM，容量有限 / 注册较繁琐 |
|
||||
| Hetzner | CX22 | 2 vCPU, 4GB RAM | €3.79 (~$4) | 最便宜的付费方案 |
|
||||
| DigitalOcean | Basic | 1 vCPU, 1GB RAM | $6 | 界面简洁，文档完善 |
|
||||
| Vultr | Cloud Compute | 1 vCPU, 1GB RAM | $6 | 节点位置多 |
|
||||
| Linode | Nanode | 1 vCPU, 1GB RAM | $5 | 现为 Akamai 旗下 |
|
||||
|
||||
**选择提供商：**
|
||||
|
||||
- DigitalOcean：最简单的用户体验 + 可预期的设置流程（本指南）
|
||||
- Hetzner：性价比高（参见 [Hetzner 指南](/platforms/hetzner)）
|
||||
- Oracle Cloud：可以每月 $0，但配置较繁琐且仅支持 ARM（参见 [Oracle 指南](/platforms/oracle)）
|
||||
|
||||
---
|
||||
|
||||
## 前提条件
|
||||
|
||||
- DigitalOcean 账户（[注册可获 $200 免费额度](https://m.do.co/c/signup)）
|
||||
- SSH 密钥对（或愿意使用密码认证）
|
||||
- 约 20 分钟
|
||||
|
||||
## 1）创建 Droplet
|
||||
|
||||
1. 登录 [DigitalOcean](https://cloud.digitalocean.com/)
|
||||
2. 点击 **Create → Droplets**
|
||||
3. 选择：
|
||||
- **区域：** 离你（或你的用户）最近的
|
||||
- **镜像：** Ubuntu 24.04 LTS
|
||||
- **规格：** Basic → Regular → **$6/月**（1 vCPU, 1GB RAM, 25GB SSD）
|
||||
- **认证：** SSH 密钥（推荐）或密码
|
||||
4. 点击 **Create Droplet**
|
||||
5. 记下 IP 地址
|
||||
|
||||
## 2）通过 SSH 连接
|
||||
|
||||
```bash
|
||||
ssh root@YOUR_DROPLET_IP
|
||||
```
|
||||
|
||||
## 3）安装 OpenClaw
|
||||
|
||||
```bash
|
||||
# 更新系统
|
||||
apt update && apt upgrade -y
|
||||
|
||||
# 安装 Node.js 22
|
||||
curl -fsSL https://deb.nodesource.com/setup_22.x | bash -
|
||||
apt install -y nodejs
|
||||
|
||||
# 安装 OpenClaw
|
||||
curl -fsSL https://openclaw.ai/install.sh | bash
|
||||
|
||||
# 验证
|
||||
openclaw --version
|
||||
```
|
||||
|
||||
## 4）运行上手引导
|
||||
|
||||
```bash
|
||||
openclaw onboard --install-daemon
|
||||
```
|
||||
|
||||
向导将引导你完成：
|
||||
|
||||
- 模型认证（API 密钥或 OAuth）
|
||||
- 渠道设置（Telegram、WhatsApp、Discord 等）
|
||||
- Gateway 令牌（自动生成）
|
||||
- 守护进程安装（systemd）
|
||||
|
||||
## 5）验证 Gateway
|
||||
|
||||
```bash
|
||||
# 检查状态
|
||||
openclaw status
|
||||
|
||||
# 检查服务
|
||||
systemctl --user status openclaw-gateway.service
|
||||
|
||||
# 查看日志
|
||||
journalctl --user -u openclaw-gateway.service -f
|
||||
```
|
||||
|
||||
## 6）访问控制面板
|
||||
|
||||
Gateway 默认绑定到回环地址。要访问控制面板 UI：
|
||||
|
||||
**方案 A：SSH 隧道（推荐）**
|
||||
|
||||
```bash
|
||||
# 从你的本地机器
|
||||
ssh -L 18789:localhost:18789 root@YOUR_DROPLET_IP
|
||||
|
||||
# 然后打开：http://localhost:18789
|
||||
```
|
||||
|
||||
**方案 B：Tailscale Serve（HTTPS，仅回环）**
|
||||
|
||||
```bash
|
||||
# 在 Droplet 上
|
||||
curl -fsSL https://tailscale.com/install.sh | sh
|
||||
tailscale up
|
||||
|
||||
# 配置 Gateway 使用 Tailscale Serve
|
||||
openclaw config set gateway.tailscale.mode serve
|
||||
openclaw gateway restart
|
||||
```
|
||||
|
||||
打开：`https://<magicdns>/`
|
||||
|
||||
注意事项：
|
||||
|
||||
- Serve 保持 Gateway 仅绑定回环地址，并通过 Tailscale 身份头进行认证。
|
||||
- 如需使用令牌/密码认证，请设置 `gateway.auth.allowTailscale: false` 或使用 `gateway.auth.mode: "password"`。
|
||||
|
||||
**方案 C：Tailnet 绑定（不使用 Serve）**
|
||||
|
||||
```bash
|
||||
openclaw config set gateway.bind tailnet
|
||||
openclaw gateway restart
|
||||
```
|
||||
|
||||
打开：`http://<tailscale-ip>:18789`（需要令牌）。
|
||||
|
||||
## 7）连接你的渠道
|
||||
|
||||
### Telegram
|
||||
|
||||
```bash
|
||||
openclaw pairing list telegram
|
||||
openclaw pairing approve telegram <CODE>
|
||||
```
|
||||
|
||||
### WhatsApp
|
||||
|
||||
```bash
|
||||
openclaw channels login whatsapp
|
||||
# 扫描二维码
|
||||
```
|
||||
|
||||
其他提供商请参阅[渠道](/channels)。
|
||||
|
||||
---
|
||||
|
||||
## 1GB RAM 的优化建议
|
||||
|
||||
$6 的 Droplet 只有 1GB RAM。为保持运行流畅：
|
||||
|
||||
### 添加交换空间（推荐）
|
||||
|
||||
```bash
|
||||
fallocate -l 2G /swapfile
|
||||
chmod 600 /swapfile
|
||||
mkswap /swapfile
|
||||
swapon /swapfile
|
||||
echo '/swapfile none swap sw 0 0' >> /etc/fstab
|
||||
```
|
||||
|
||||
### 使用更轻量的模型
|
||||
|
||||
如果遇到内存不足（OOM），可以考虑：
|
||||
|
||||
- 使用基于 API 的模型（Claude、GPT）而非本地模型
|
||||
- 将 `agents.defaults.model.primary` 设置为更小的模型
|
||||
|
||||
### 监控内存
|
||||
|
||||
```bash
|
||||
free -h
|
||||
htop
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 持久化
|
||||
|
||||
所有状态存储在：
|
||||
|
||||
- `~/.openclaw/` — 配置、凭据、会话数据
|
||||
- `~/.openclaw/workspace/` — 工作区（SOUL.md、记忆等）
|
||||
|
||||
这些内容在重启后不会丢失。定期备份：
|
||||
|
||||
```bash
|
||||
tar -czvf openclaw-backup.tar.gz ~/.openclaw ~/.openclaw/workspace
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Oracle Cloud 免费替代方案
|
||||
|
||||
Oracle Cloud 提供 **Always Free** ARM 实例，性能远超此处任何付费方案——每月 $0。
|
||||
|
||||
| 你将获得 | 规格 |
|
||||
| -------------- | ---------------- |
|
||||
| **4 OCPU** | ARM Ampere A1 |
|
||||
| **24GB RAM** | 绰绰有余 |
|
||||
| **200GB 存储** | 块存储卷 |
|
||||
| **永久免费** | 不会扣信用卡费用 |
|
||||
|
||||
**注意事项：**
|
||||
|
||||
- 注册过程可能较繁琐（失败时请重试）
|
||||
- ARM 架构——大多数工具可正常工作，但部分二进制文件需要 ARM 构建版本
|
||||
|
||||
完整设置指南请参阅 [Oracle Cloud](/platforms/oracle)。注册技巧和注册流程故障排除请参阅此[社区指南](https://gist.github.com/rssnyder/51e3cfedd730e7dd5f4a816143b25dbd)。
|
||||
|
||||
---
|
||||
|
||||
## 故障排除
|
||||
|
||||
### Gateway 无法启动
|
||||
|
||||
```bash
|
||||
openclaw gateway status
|
||||
openclaw doctor --non-interactive
|
||||
journalctl -u openclaw --no-pager -n 50
|
||||
```
|
||||
|
||||
### 端口已被占用
|
||||
|
||||
```bash
|
||||
lsof -i :18789
|
||||
kill <PID>
|
||||
```
|
||||
|
||||
### 内存不足
|
||||
|
||||
```bash
|
||||
# 检查内存
|
||||
free -h
|
||||
|
||||
# 添加更多交换空间
|
||||
# 或升级到 $12/月的 Droplet（2GB RAM）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 另请参阅
|
||||
|
||||
- [Hetzner 指南](/platforms/hetzner) — 更便宜，性能更强
|
||||
- [Docker 安装](/install/docker) — 容器化设置
|
||||
- [Tailscale](/gateway/tailscale) — 安全远程访问
|
||||
- [配置](/gateway/configuration) — 完整配置参考
|
||||
127
docs/zh-CN/platforms/exe-dev.md
Normal file
127
docs/zh-CN/platforms/exe-dev.md
Normal file
@@ -0,0 +1,127 @@
|
||||
---
|
||||
read_when:
|
||||
- 你想要一个便宜的常驻 Linux 主机来运行 Gateway
|
||||
- 你想在不自行运维 VPS 的情况下远程访问控制面板 UI
|
||||
summary: 在 exe.dev 上运行 OpenClaw Gateway（虚拟机 + HTTPS 代理）以实现远程访问
|
||||
title: exe.dev
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T21:20:17Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: d4697efb0ff219f6222a932e89572182d311b267c393297b052c1296a6936eda
|
||||
source_path: platforms/exe-dev.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# exe.dev
|
||||
|
||||
目标：在 exe.dev 虚拟机上运行 OpenClaw Gateway，通过以下地址从你的笔记本访问：`https://<vm-name>.exe.xyz`
|
||||
|
||||
本页假设使用 exe.dev 的默认 **exeuntu** 镜像。如果你选择了其他发行版，请相应调整软件包。
|
||||
|
||||
## 新手快速路径
|
||||
|
||||
1. [https://exe.new/openclaw](https://exe.new/openclaw)
|
||||
2. 根据需要填入你的认证密钥/令牌
|
||||
3. 点击虚拟机旁边的"Agent"，然后等待...
|
||||
4. ???
|
||||
5. 完成
|
||||
|
||||
## 你需要什么
|
||||
|
||||
- exe.dev 账户
|
||||
- 通过 `ssh exe.dev` 访问 [exe.dev](https://exe.dev) 虚拟机（可选）
|
||||
|
||||
## 使用 Shelley 自动安装
|
||||
|
||||
Shelley 是 [exe.dev](https://exe.dev) 的智能体，可以通过我们的提示词即时安装 OpenClaw。使用的提示词如下：
|
||||
|
||||
```
|
||||
Set up OpenClaw (https://docs.openclaw.ai/install) on this VM. Use the non-interactive and accept-risk flags for openclaw onboarding. Add the supplied auth or token as needed. Configure nginx to forward from the default port 18789 to the root location on the default enabled site config, making sure to enable Websocket support. Pairing is done by "openclaw devices list" and "openclaw device approve <request id>". Make sure the dashboard shows that OpenClaw's health is OK. exe.dev handles forwarding from port 8000 to port 80/443 and HTTPS for us, so the final "reachable" should be <vm-name>.exe.xyz, without port specification.
|
||||
```
|
||||
|
||||
## 手动安装
|
||||
|
||||
## 1）创建虚拟机
|
||||
|
||||
从你的设备：
|
||||
|
||||
```bash
|
||||
ssh exe.dev new
|
||||
```
|
||||
|
||||
然后连接：
|
||||
|
||||
```bash
|
||||
ssh <vm-name>.exe.xyz
|
||||
```
|
||||
|
||||
提示：保持此虚拟机为**有状态**。OpenClaw 将状态存储在 `~/.openclaw/` 和 `~/.openclaw/workspace/` 下。
|
||||
|
||||
## 2）安装前置依赖（在虚拟机上）
|
||||
|
||||
```bash
|
||||
sudo apt-get update
|
||||
sudo apt-get install -y git curl jq ca-certificates openssl
|
||||
```
|
||||
|
||||
## 3）安装 OpenClaw
|
||||
|
||||
运行 OpenClaw 安装脚本：
|
||||
|
||||
```bash
|
||||
curl -fsSL https://openclaw.ai/install.sh | bash
|
||||
```
|
||||
|
||||
## 4）配置 nginx 将 OpenClaw 代理到端口 8000
|
||||
|
||||
编辑 `/etc/nginx/sites-enabled/default`：
|
||||
|
||||
```
|
||||
server {
|
||||
listen 80 default_server;
|
||||
listen [::]:80 default_server;
|
||||
listen 8000;
|
||||
listen [::]:8000;
|
||||
|
||||
server_name _;
|
||||
|
||||
location / {
|
||||
proxy_pass http://127.0.0.1:18789;
|
||||
proxy_http_version 1.1;
|
||||
|
||||
# WebSocket 支持
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection "upgrade";
|
||||
|
||||
# 标准代理头
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
|
||||
# 长连接超时设置
|
||||
proxy_read_timeout 86400s;
|
||||
proxy_send_timeout 86400s;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 5）访问 OpenClaw 并授予权限
|
||||
|
||||
访问 `https://<vm-name>.exe.xyz/?token=YOUR-TOKEN-FROM-TERMINAL`。使用 `openclaw devices list` 和 `openclaw device approve` 审批设备。如果不确定，可以从浏览器使用 Shelley！
|
||||
|
||||
## 远程访问
|
||||
|
||||
远程访问由 [exe.dev](https://exe.dev) 的认证机制处理。默认情况下，端口 8000 的 HTTP 流量会被转发到 `https://<vm-name>.exe.xyz`，并通过邮箱认证。
|
||||
|
||||
## 更新
|
||||
|
||||
```bash
|
||||
npm i -g openclaw@latest
|
||||
openclaw doctor
|
||||
openclaw gateway restart
|
||||
openclaw health
|
||||
```
|
||||
|
||||
指南：[更新](/install/updating)
|
||||
490
docs/zh-CN/platforms/fly.md
Normal file
490
docs/zh-CN/platforms/fly.md
Normal file
@@ -0,0 +1,490 @@
|
||||
---
|
||||
description: Deploy OpenClaw on Fly.io
|
||||
title: Fly.io
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T21:21:15Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: a00bae43e416112eb269126445c51492a30abe9e136d89e161fc4193314a876f
|
||||
source_path: platforms/fly.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Fly.io 部署
|
||||
|
||||
**目标：** 在 [Fly.io](https://fly.io) 机器上运行 OpenClaw Gateway，配备持久化存储、自动 HTTPS 和 Discord/渠道访问。
|
||||
|
||||
## 你需要什么
|
||||
|
||||
- 已安装 [flyctl CLI](https://fly.io/docs/hands-on/install-flyctl/)
|
||||
- Fly.io 账户（免费套餐即可）
|
||||
- 模型认证：Anthropic API 密钥（或其他提供商密钥）
|
||||
- 渠道凭据：Discord 机器人令牌、Telegram 令牌等
|
||||
|
||||
## 新手快速路径
|
||||
|
||||
1. 克隆仓库 → 自定义 `fly.toml`
|
||||
2. 创建应用 + 卷 → 设置密钥
|
||||
3. 使用 `fly deploy` 部署
|
||||
4. 通过 SSH 创建配置或使用控制面板 UI
|
||||
|
||||
## 1）创建 Fly 应用
|
||||
|
||||
```bash
|
||||
# 克隆仓库
|
||||
git clone https://github.com/openclaw/openclaw.git
|
||||
cd openclaw
|
||||
|
||||
# 创建新的 Fly 应用（选择你自己的名称）
|
||||
fly apps create my-openclaw
|
||||
|
||||
# 创建持久化卷（1GB 通常足够）
|
||||
fly volumes create openclaw_data --size 1 --region iad
|
||||
```
|
||||
|
||||
**提示：** 选择离你最近的区域。常见选项：`lhr`（伦敦）、`iad`（弗吉尼亚）、`sjc`（圣何塞）。
|
||||
|
||||
## 2）配置 fly.toml
|
||||
|
||||
编辑 `fly.toml` 以匹配你的应用名称和需求。
|
||||
|
||||
**安全提示：** 默认配置会暴露公共 URL。如需无公网 IP 的加固部署，请参阅[私有部署](#私有部署加固)或使用 `fly.private.toml`。
|
||||
|
||||
```toml
|
||||
app = "my-openclaw" # 你的应用名称
|
||||
primary_region = "iad"
|
||||
|
||||
[build]
|
||||
dockerfile = "Dockerfile"
|
||||
|
||||
[env]
|
||||
NODE_ENV = "production"
|
||||
OPENCLAW_PREFER_PNPM = "1"
|
||||
OPENCLAW_STATE_DIR = "/data"
|
||||
NODE_OPTIONS = "--max-old-space-size=1536"
|
||||
|
||||
[processes]
|
||||
app = "node dist/index.js gateway --allow-unconfigured --port 3000 --bind lan"
|
||||
|
||||
[http_service]
|
||||
internal_port = 3000
|
||||
force_https = true
|
||||
auto_stop_machines = false
|
||||
auto_start_machines = true
|
||||
min_machines_running = 1
|
||||
processes = ["app"]
|
||||
|
||||
[[vm]]
|
||||
size = "shared-cpu-2x"
|
||||
memory = "2048mb"
|
||||
|
||||
[mounts]
|
||||
source = "openclaw_data"
|
||||
destination = "/data"
|
||||
```
|
||||
|
||||
**关键设置：**
|
||||
|
||||
| 设置 | 原因 |
|
||||
| ------------------------------ | ------------------------------------------------------------------------- |
|
||||
| `--bind lan` | 绑定到 `0.0.0.0`，使 Fly 的代理能够访问 Gateway |
|
||||
| `--allow-unconfigured` | 无需配置文件即可启动（之后再创建） |
|
||||
| `internal_port = 3000` | 必须与 `--port 3000`（或 `OPENCLAW_GATEWAY_PORT`）匹配，用于 Fly 健康检查 |
|
||||
| `memory = "2048mb"` | 512MB 太小；推荐 2GB |
|
||||
| `OPENCLAW_STATE_DIR = "/data"` | 将状态持久化到卷上 |
|
||||
|
||||
## 3）设置密钥
|
||||
|
||||
```bash
|
||||
# 必需：Gateway 令牌（用于非回环绑定）
|
||||
fly secrets set OPENCLAW_GATEWAY_TOKEN=$(openssl rand -hex 32)
|
||||
|
||||
# 模型提供商 API 密钥
|
||||
fly secrets set ANTHROPIC_API_KEY=sk-ant-...
|
||||
|
||||
# 可选：其他提供商
|
||||
fly secrets set OPENAI_API_KEY=sk-...
|
||||
fly secrets set GOOGLE_API_KEY=...
|
||||
|
||||
# 渠道令牌
|
||||
fly secrets set DISCORD_BOT_TOKEN=MTQ...
|
||||
```
|
||||
|
||||
**注意事项：**
|
||||
|
||||
- 非回环绑定（`--bind lan`）出于安全需要 `OPENCLAW_GATEWAY_TOKEN`。
|
||||
- 请像对待密码一样对待这些令牌。
|
||||
- **所有 API 密钥和令牌优先使用环境变量而非配置文件**。这样可以避免密钥出现在 `openclaw.json` 中，防止意外暴露或被记录到日志。
|
||||
|
||||
## 4）部署
|
||||
|
||||
```bash
|
||||
fly deploy
|
||||
```
|
||||
|
||||
首次部署会构建 Docker 镜像（约 2-3 分钟）。后续部署会更快。
|
||||
|
||||
部署后验证：
|
||||
|
||||
```bash
|
||||
fly status
|
||||
fly logs
|
||||
```
|
||||
|
||||
你应该看到：
|
||||
|
||||
```
|
||||
[gateway] listening on ws://0.0.0.0:3000 (PID xxx)
|
||||
[discord] logged in to discord as xxx
|
||||
```
|
||||
|
||||
## 5）创建配置文件
|
||||
|
||||
通过 SSH 连接到机器以创建正式配置：
|
||||
|
||||
```bash
|
||||
fly ssh console
|
||||
```
|
||||
|
||||
创建配置目录和文件：
|
||||
|
||||
```bash
|
||||
mkdir -p /data
|
||||
cat > /data/openclaw.json << 'EOF'
|
||||
{
|
||||
"agents": {
|
||||
"defaults": {
|
||||
"model": {
|
||||
"primary": "anthropic/claude-opus-4-5",
|
||||
"fallbacks": ["anthropic/claude-sonnet-4-5", "openai/gpt-4o"]
|
||||
},
|
||||
"maxConcurrent": 4
|
||||
},
|
||||
"list": [
|
||||
{
|
||||
"id": "main",
|
||||
"default": true
|
||||
}
|
||||
]
|
||||
},
|
||||
"auth": {
|
||||
"profiles": {
|
||||
"anthropic:default": { "mode": "token", "provider": "anthropic" },
|
||||
"openai:default": { "mode": "token", "provider": "openai" }
|
||||
}
|
||||
},
|
||||
"bindings": [
|
||||
{
|
||||
"agentId": "main",
|
||||
"match": { "channel": "discord" }
|
||||
}
|
||||
],
|
||||
"channels": {
|
||||
"discord": {
|
||||
"enabled": true,
|
||||
"groupPolicy": "allowlist",
|
||||
"guilds": {
|
||||
"YOUR_GUILD_ID": {
|
||||
"channels": { "general": { "allow": true } },
|
||||
"requireMention": false
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"gateway": {
|
||||
"mode": "local",
|
||||
"bind": "auto"
|
||||
},
|
||||
"meta": {
|
||||
"lastTouchedVersion": "2026.1.29"
|
||||
}
|
||||
}
|
||||
EOF
|
||||
```
|
||||
|
||||
**注意：** 当 `OPENCLAW_STATE_DIR=/data` 时，配置路径为 `/data/openclaw.json`。
|
||||
|
||||
**注意：** Discord 令牌可以来自：
|
||||
|
||||
- 环境变量：`DISCORD_BOT_TOKEN`（推荐用于密钥）
|
||||
- 配置文件：`channels.discord.token`
|
||||
|
||||
如果使用环境变量，无需在配置中添加令牌。Gateway 会自动读取 `DISCORD_BOT_TOKEN`。
|
||||
|
||||
重启以应用配置：
|
||||
|
||||
```bash
|
||||
exit
|
||||
fly machine restart <machine-id>
|
||||
```
|
||||
|
||||
## 6）访问 Gateway
|
||||
|
||||
### 控制面板 UI
|
||||
|
||||
在浏览器中打开：
|
||||
|
||||
```bash
|
||||
fly open
|
||||
```
|
||||
|
||||
或访问 `https://my-openclaw.fly.dev/`
|
||||
|
||||
粘贴你的 Gateway 令牌（即 `OPENCLAW_GATEWAY_TOKEN` 的值）进行认证。
|
||||
|
||||
### 日志
|
||||
|
||||
```bash
|
||||
fly logs # 实时日志
|
||||
fly logs --no-tail # 最近的日志
|
||||
```
|
||||
|
||||
### SSH 控制台
|
||||
|
||||
```bash
|
||||
fly ssh console
|
||||
```
|
||||
|
||||
## 故障排除
|
||||
|
||||
### "App is not listening on expected address"
|
||||
|
||||
Gateway 绑定到了 `127.0.0.1` 而不是 `0.0.0.0`。
|
||||
|
||||
**修复：** 在 `fly.toml` 的进程命令中添加 `--bind lan`。
|
||||
|
||||
### 健康检查失败 / 连接被拒绝
|
||||
|
||||
Fly 无法通过配置的端口访问 Gateway。
|
||||
|
||||
**修复：** 确保 `internal_port` 与 Gateway 端口匹配（设置 `--port 3000` 或 `OPENCLAW_GATEWAY_PORT=3000`）。
|
||||
|
||||
### 内存不足（OOM）/ 内存问题
|
||||
|
||||
容器持续重启或被终止。迹象：`SIGABRT`、`v8::internal::Runtime_AllocateInYoungGeneration` 或无声重启。
|
||||
|
||||
**修复：** 在 `fly.toml` 中增加内存：
|
||||
|
||||
```toml
|
||||
[[vm]]
|
||||
memory = "2048mb"
|
||||
```
|
||||
|
||||
或更新现有机器：
|
||||
|
||||
```bash
|
||||
fly machine update <machine-id> --vm-memory 2048 -y
|
||||
```
|
||||
|
||||
**注意：** 512MB 太小。1GB 可能可以工作但在负载或详细日志记录下可能 OOM。**推荐 2GB。**
|
||||
|
||||
### Gateway 锁文件问题
|
||||
|
||||
Gateway 拒绝启动并报"already running"错误。
|
||||
|
||||
这发生在容器重启但 PID 锁文件在卷上持久保留时。
|
||||
|
||||
**修复：** 删除锁文件：
|
||||
|
||||
```bash
|
||||
fly ssh console --command "rm -f /data/gateway.*.lock"
|
||||
fly machine restart <machine-id>
|
||||
```
|
||||
|
||||
锁文件位于 `/data/gateway.*.lock`（不在子目录中）。
|
||||
|
||||
### 配置未被读取
|
||||
|
||||
如果使用 `--allow-unconfigured`，Gateway 会创建一个最小配置。你在 `/data/openclaw.json` 的自定义配置应在重启后被读取。
|
||||
|
||||
验证配置是否存在：
|
||||
|
||||
```bash
|
||||
fly ssh console --command "cat /data/openclaw.json"
|
||||
```
|
||||
|
||||
### 通过 SSH 写入配置
|
||||
|
||||
`fly ssh console -C` 命令不支持 shell 重定向。要写入配置文件：
|
||||
|
||||
```bash
|
||||
# 使用 echo + tee（从本地管道到远程）
|
||||
echo '{"your":"config"}' | fly ssh console -C "tee /data/openclaw.json"
|
||||
|
||||
# 或使用 sftp
|
||||
fly sftp shell
|
||||
> put /local/path/config.json /data/openclaw.json
|
||||
```
|
||||
|
||||
**注意：** 如果文件已存在，`fly sftp` 可能会失败。请先删除：
|
||||
|
||||
```bash
|
||||
fly ssh console --command "rm /data/openclaw.json"
|
||||
```
|
||||
|
||||
### 状态未持久化
|
||||
|
||||
如果重启后凭据或会话丢失，说明状态目录写入了容器文件系统。
|
||||
|
||||
**修复：** 确保 `fly.toml` 中设置了 `OPENCLAW_STATE_DIR=/data` 并重新部署。
|
||||
|
||||
## 更新
|
||||
|
||||
```bash
|
||||
# 拉取最新更改
|
||||
git pull
|
||||
|
||||
# 重新部署
|
||||
fly deploy
|
||||
|
||||
# 检查健康状态
|
||||
fly status
|
||||
fly logs
|
||||
```
|
||||
|
||||
### 更新机器命令
|
||||
|
||||
如果需要在不完全重新部署的情况下更改启动命令：
|
||||
|
||||
```bash
|
||||
# 获取机器 ID
|
||||
fly machines list
|
||||
|
||||
# 更新命令
|
||||
fly machine update <machine-id> --command "node dist/index.js gateway --port 3000 --bind lan" -y
|
||||
|
||||
# 或同时增加内存
|
||||
fly machine update <machine-id> --vm-memory 2048 --command "node dist/index.js gateway --port 3000 --bind lan" -y
|
||||
```
|
||||
|
||||
**注意：** `fly deploy` 后，机器命令可能会重置为 `fly.toml` 中的内容。如果你做了手动更改，请在部署后重新应用。
|
||||
|
||||
## 私有部署（加固）
|
||||
|
||||
默认情况下，Fly 分配公网 IP，使你的 Gateway 可通过 `https://your-app.fly.dev` 访问。这很方便，但意味着你的部署可被互联网扫描器（Shodan、Censys 等）发现。
|
||||
|
||||
如需**无公网暴露**的加固部署，请使用私有模板。
|
||||
|
||||
### 何时使用私有部署
|
||||
|
||||
- 你只进行**出站**调用/消息（无入站 webhook）
|
||||
- 你使用 **ngrok 或 Tailscale** 隧道处理 webhook 回调
|
||||
- 你通过 **SSH、代理或 WireGuard** 访问 Gateway 而非浏览器
|
||||
- 你希望部署**对互联网扫描器不可见**
|
||||
|
||||
### 设置
|
||||
|
||||
使用 `fly.private.toml` 代替标准配置：
|
||||
|
||||
```bash
|
||||
# 使用私有配置部署
|
||||
fly deploy -c fly.private.toml
|
||||
```
|
||||
|
||||
或转换现有部署：
|
||||
|
||||
```bash
|
||||
# 列出当前 IP
|
||||
fly ips list -a my-openclaw
|
||||
|
||||
# 释放公网 IP
|
||||
fly ips release <public-ipv4> -a my-openclaw
|
||||
fly ips release <public-ipv6> -a my-openclaw
|
||||
|
||||
# 切换到私有配置，使未来的部署不再分配公网 IP
|
||||
# （移除 [http_service] 或使用私有模板部署）
|
||||
fly deploy -c fly.private.toml
|
||||
|
||||
# 分配仅私有的 IPv6
|
||||
fly ips allocate-v6 --private -a my-openclaw
|
||||
```
|
||||
|
||||
之后，`fly ips list` 应该只显示 `private` 类型的 IP：
|
||||
|
||||
```
|
||||
VERSION IP TYPE REGION
|
||||
v6 fdaa:x:x:x:x::x private global
|
||||
```
|
||||
|
||||
### 访问私有部署
|
||||
|
||||
由于没有公网 URL，请使用以下方法之一：
|
||||
|
||||
**方案 1：本地代理（最简单）**
|
||||
|
||||
```bash
|
||||
# 将本地端口 3000 转发到应用
|
||||
fly proxy 3000:3000 -a my-openclaw
|
||||
|
||||
# 然后在浏览器中打开 http://localhost:3000
|
||||
```
|
||||
|
||||
**方案 2：WireGuard VPN**
|
||||
|
||||
```bash
|
||||
# 创建 WireGuard 配置（一次性）
|
||||
fly wireguard create
|
||||
|
||||
# 导入到 WireGuard 客户端，然后通过内部 IPv6 访问
|
||||
# 示例：http://[fdaa:x:x:x:x::x]:3000
|
||||
```
|
||||
|
||||
**方案 3：仅 SSH**
|
||||
|
||||
```bash
|
||||
fly ssh console -a my-openclaw
|
||||
```
|
||||
|
||||
### 私有部署中的 Webhook
|
||||
|
||||
如果你需要 webhook 回调（Twilio、Telnyx 等）但不想公网暴露：
|
||||
|
||||
1. **ngrok 隧道** - 在容器内或作为 sidecar 运行 ngrok
|
||||
2. **Tailscale Funnel** - 通过 Tailscale 暴露特定路径
|
||||
3. **仅出站** - 某些提供商（Twilio）在无 webhook 的情况下也能正常进行出站呼叫
|
||||
|
||||
使用 ngrok 的语音通话配置示例：
|
||||
|
||||
```json
|
||||
{
|
||||
"plugins": {
|
||||
"entries": {
|
||||
"voice-call": {
|
||||
"enabled": true,
|
||||
"config": {
|
||||
"provider": "twilio",
|
||||
"tunnel": { "provider": "ngrok" }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
ngrok 隧道在容器内运行，提供公共 webhook URL 而不暴露 Fly 应用本身。
|
||||
|
||||
### 安全优势
|
||||
|
||||
| 方面 | 公网 | 私有 |
|
||||
| ---------------- | -------- | -------- |
|
||||
| 互联网扫描器 | 可被发现 | 隐藏 |
|
||||
| 直接攻击 | 可能 | 被阻止 |
|
||||
| 控制面板 UI 访问 | 浏览器 | 代理/VPN |
|
||||
| Webhook 投递 | 直接 | 通过隧道 |
|
||||
|
||||
## 注意事项
|
||||
|
||||
- Fly.io 使用 **x86 架构**（非 ARM）
|
||||
- Dockerfile 兼容两种架构
|
||||
- WhatsApp/Telegram 上手引导请使用 `fly ssh console`
|
||||
- 持久化数据存储在 `/data` 卷上
|
||||
- Signal 需要 Java + signal-cli；请使用自定义镜像并保持内存在 2GB+ 以上。
|
||||
|
||||
## 费用
|
||||
|
||||
使用推荐配置（`shared-cpu-2x`，2GB RAM）：
|
||||
|
||||
- 每月约 $10-15，取决于使用量
|
||||
- 免费套餐包含一定额度
|
||||
|
||||
详情参见 [Fly.io 定价](https://fly.io/docs/about/pricing/)。
|
||||
510
docs/zh-CN/platforms/gcp.md
Normal file
510
docs/zh-CN/platforms/gcp.md
Normal file
@@ -0,0 +1,510 @@
|
||||
---
|
||||
read_when:
|
||||
- 您希望在 GCP 上全天候运行 OpenClaw
|
||||
- 您希望在自己的虚拟机上运行生产级、始终在线的 Gateway
|
||||
- 您希望完全掌控持久化、二进制文件和重启行为
|
||||
summary: 在 GCP Compute Engine 虚拟机上全天候运行 OpenClaw Gateway（Docker），并实现持久化状态存储
|
||||
title: GCP
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T21:33:10Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: abb236dd421505d307bb3869340c9a0c940de095b93af9ad1f130cc08a9deadb
|
||||
source_path: platforms/gcp.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 在 GCP Compute Engine 上运行 OpenClaw（Docker，生产环境 VPS 指南）
|
||||
|
||||
## 目标
|
||||
|
||||
使用 Docker 在 GCP Compute Engine 虚拟机上运行持久化的 OpenClaw Gateway，实现持久状态存储、内置二进制文件和安全的重启行为。
|
||||
|
||||
如果您想"以每月约 $5-12 的成本全天候运行 OpenClaw"，这是在 Google Cloud 上的可靠方案。
|
||||
价格因机器类型和区域而异；选择适合您工作负载的最小虚拟机，如果遇到 OOM 再进行扩容。
|
||||
|
||||
## 我们要做什么（简单说明）？
|
||||
|
||||
- 创建 GCP 项目并启用计费
|
||||
- 创建 Compute Engine 虚拟机
|
||||
- 安装 Docker（隔离的应用运行时）
|
||||
- 在 Docker 中启动 OpenClaw Gateway
|
||||
- 将 `~/.openclaw` + `~/.openclaw/workspace` 持久化到宿主机（重启/重建后数据不丢失）
|
||||
- 通过 SSH 隧道从笔记本电脑访问控制界面
|
||||
|
||||
Gateway 可通过以下方式访问：
|
||||
|
||||
- 从笔记本电脑进行 SSH 端口转发
|
||||
- 如果您自行管理防火墙和令牌，可直接暴露端口
|
||||
|
||||
本指南使用 GCP Compute Engine 上的 Debian。
|
||||
Ubuntu 同样适用；请相应地映射软件包。
|
||||
有关通用 Docker 流程，请参阅 [Docker](/install/docker)。
|
||||
|
||||
---
|
||||
|
||||
## 快速路径（有经验的运维人员）
|
||||
|
||||
1. 创建 GCP 项目 + 启用 Compute Engine API
|
||||
2. 创建 Compute Engine 虚拟机（e2-small，Debian 12，20GB）
|
||||
3. SSH 连接到虚拟机
|
||||
4. 安装 Docker
|
||||
5. 克隆 OpenClaw 仓库
|
||||
6. 创建持久化宿主机目录
|
||||
7. 配置 `.env` 和 `docker-compose.yml`
|
||||
8. 内置所需二进制文件，构建并启动
|
||||
|
||||
---
|
||||
|
||||
## 前提条件
|
||||
|
||||
- GCP 账户（e2-micro 可享受免费层级）
|
||||
- 已安装 gcloud CLI（或使用 Cloud Console）
|
||||
- 笔记本电脑可进行 SSH 访问
|
||||
- 基本的 SSH 操作和复制/粘贴能力
|
||||
- 约 20-30 分钟
|
||||
- Docker 和 Docker Compose
|
||||
- 模型认证凭据
|
||||
- 可选的提供商凭据
|
||||
- WhatsApp 二维码
|
||||
- Telegram 机器人令牌
|
||||
- Gmail OAuth
|
||||
|
||||
---
|
||||
|
||||
## 1）安装 gcloud CLI（或使用 Console）
|
||||
|
||||
**选项 A：gcloud CLI**（推荐用于自动化）
|
||||
|
||||
从 https://cloud.google.com/sdk/docs/install 安装
|
||||
|
||||
初始化并认证：
|
||||
|
||||
```bash
|
||||
gcloud init
|
||||
gcloud auth login
|
||||
```
|
||||
|
||||
**选项 B：Cloud Console**
|
||||
|
||||
所有步骤均可通过 https://console.cloud.google.com 的 Web 界面完成
|
||||
|
||||
---
|
||||
|
||||
## 2）创建 GCP 项目
|
||||
|
||||
**CLI：**
|
||||
|
||||
```bash
|
||||
gcloud projects create my-openclaw-project --name="OpenClaw Gateway"
|
||||
gcloud config set project my-openclaw-project
|
||||
```
|
||||
|
||||
在 https://console.cloud.google.com/billing 启用计费（Compute Engine 必需）。
|
||||
|
||||
启用 Compute Engine API：
|
||||
|
||||
```bash
|
||||
gcloud services enable compute.googleapis.com
|
||||
```
|
||||
|
||||
**Console：**
|
||||
|
||||
1. 前往 IAM & Admin > Create Project
|
||||
2. 命名并创建
|
||||
3. 为项目启用计费
|
||||
4. 导航至 APIs & Services > Enable APIs > 搜索 "Compute Engine API" > 启用
|
||||
|
||||
---
|
||||
|
||||
## 3）创建虚拟机
|
||||
|
||||
**机器类型：**
|
||||
|
||||
| 类型 | 规格 | 费用 | 备注 |
|
||||
| -------- | ------------------------ | -------------- | ---------------- |
|
||||
| e2-small | 2 vCPU，2GB 内存 | 约 $12/月 | 推荐 |
|
||||
| e2-micro | 2 vCPU（共享），1GB 内存 | 可享受免费层级 | 高负载下可能 OOM |
|
||||
|
||||
**CLI：**
|
||||
|
||||
```bash
|
||||
gcloud compute instances create openclaw-gateway \
|
||||
--zone=us-central1-a \
|
||||
--machine-type=e2-small \
|
||||
--boot-disk-size=20GB \
|
||||
--image-family=debian-12 \
|
||||
--image-project=debian-cloud
|
||||
```
|
||||
|
||||
**Console：**
|
||||
|
||||
1. 前往 Compute Engine > VM instances > Create instance
|
||||
2. 名称：`openclaw-gateway`
|
||||
3. 区域：`us-central1`，可用区：`us-central1-a`
|
||||
4. 机器类型：`e2-small`
|
||||
5. 启动磁盘：Debian 12，20GB
|
||||
6. 创建
|
||||
|
||||
---
|
||||
|
||||
## 4）SSH 连接到虚拟机
|
||||
|
||||
**CLI：**
|
||||
|
||||
```bash
|
||||
gcloud compute ssh openclaw-gateway --zone=us-central1-a
|
||||
```
|
||||
|
||||
**Console：**
|
||||
|
||||
在 Compute Engine 控制面板中点击虚拟机旁边的 "SSH" 按钮。
|
||||
|
||||
注意：虚拟机创建后，SSH 密钥传播可能需要 1-2 分钟。如果连接被拒绝，请等待后重试。
|
||||
|
||||
---
|
||||
|
||||
## 5）安装 Docker（在虚拟机上）
|
||||
|
||||
```bash
|
||||
sudo apt-get update
|
||||
sudo apt-get install -y git curl ca-certificates
|
||||
curl -fsSL https://get.docker.com | sudo sh
|
||||
sudo usermod -aG docker $USER
|
||||
```
|
||||
|
||||
注销并重新登录以使用户组变更生效：
|
||||
|
||||
```bash
|
||||
exit
|
||||
```
|
||||
|
||||
然后重新 SSH 连接：
|
||||
|
||||
```bash
|
||||
gcloud compute ssh openclaw-gateway --zone=us-central1-a
|
||||
```
|
||||
|
||||
验证：
|
||||
|
||||
```bash
|
||||
docker --version
|
||||
docker compose version
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6）克隆 OpenClaw 仓库
|
||||
|
||||
```bash
|
||||
git clone https://github.com/openclaw/openclaw.git
|
||||
cd openclaw
|
||||
```
|
||||
|
||||
本指南假设您将构建自定义镜像以确保二进制文件的持久化。
|
||||
|
||||
---
|
||||
|
||||
## 7）创建持久化宿主机目录
|
||||
|
||||
Docker 容器是临时性的。
|
||||
所有长期状态必须存储在宿主机上。
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.openclaw
|
||||
mkdir -p ~/.openclaw/workspace
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8）配置环境变量
|
||||
|
||||
在仓库根目录创建 `.env`。
|
||||
|
||||
```bash
|
||||
OPENCLAW_IMAGE=openclaw:latest
|
||||
OPENCLAW_GATEWAY_TOKEN=change-me-now
|
||||
OPENCLAW_GATEWAY_BIND=lan
|
||||
OPENCLAW_GATEWAY_PORT=18789
|
||||
|
||||
OPENCLAW_CONFIG_DIR=/home/$USER/.openclaw
|
||||
OPENCLAW_WORKSPACE_DIR=/home/$USER/.openclaw/workspace
|
||||
|
||||
GOG_KEYRING_PASSWORD=change-me-now
|
||||
XDG_CONFIG_HOME=/home/node/.openclaw
|
||||
```
|
||||
|
||||
生成强密钥：
|
||||
|
||||
```bash
|
||||
openssl rand -hex 32
|
||||
```
|
||||
|
||||
**请勿提交此文件。**
|
||||
|
||||
---
|
||||
|
||||
## 9）Docker Compose 配置
|
||||
|
||||
创建或更新 `docker-compose.yml`。
|
||||
|
||||
```yaml
|
||||
services:
|
||||
openclaw-gateway:
|
||||
image: ${OPENCLAW_IMAGE}
|
||||
build: .
|
||||
restart: unless-stopped
|
||||
env_file:
|
||||
- .env
|
||||
environment:
|
||||
- HOME=/home/node
|
||||
- NODE_ENV=production
|
||||
- TERM=xterm-256color
|
||||
- OPENCLAW_GATEWAY_BIND=${OPENCLAW_GATEWAY_BIND}
|
||||
- OPENCLAW_GATEWAY_PORT=${OPENCLAW_GATEWAY_PORT}
|
||||
- OPENCLAW_GATEWAY_TOKEN=${OPENCLAW_GATEWAY_TOKEN}
|
||||
- GOG_KEYRING_PASSWORD=${GOG_KEYRING_PASSWORD}
|
||||
- XDG_CONFIG_HOME=${XDG_CONFIG_HOME}
|
||||
- PATH=/home/linuxbrew/.linuxbrew/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
|
||||
volumes:
|
||||
- ${OPENCLAW_CONFIG_DIR}:/home/node/.openclaw
|
||||
- ${OPENCLAW_WORKSPACE_DIR}:/home/node/.openclaw/workspace
|
||||
ports:
|
||||
# 推荐：在虚拟机上保持 Gateway 仅监听回环地址；通过 SSH 隧道访问。
|
||||
# 如需公开暴露，移除 `127.0.0.1:` 前缀并相应配置防火墙。
|
||||
- "127.0.0.1:${OPENCLAW_GATEWAY_PORT}:18789"
|
||||
|
||||
# 可选：仅当您对此虚拟机运行 iOS/Android 节点并需要 Canvas 主机时使用。
|
||||
# 如果公开暴露此端口，请阅读 /gateway/security 并相应配置防火墙。
|
||||
# - "18793:18793"
|
||||
command:
|
||||
[
|
||||
"node",
|
||||
"dist/index.js",
|
||||
"gateway",
|
||||
"--bind",
|
||||
"${OPENCLAW_GATEWAY_BIND}",
|
||||
"--port",
|
||||
"${OPENCLAW_GATEWAY_PORT}",
|
||||
]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10）将所需二进制文件内置到镜像中（关键步骤）
|
||||
|
||||
在运行中的容器内安装二进制文件是一个陷阱。
|
||||
运行时安装的任何内容在重启后都会丢失。
|
||||
|
||||
所有技能所需的外部二进制文件必须在镜像构建时安装。
|
||||
|
||||
以下示例仅展示三个常见的二进制文件：
|
||||
|
||||
- `gog` 用于 Gmail 访问
|
||||
- `goplaces` 用于 Google Places
|
||||
- `wacli` 用于 WhatsApp
|
||||
|
||||
这些只是示例，并非完整列表。
|
||||
您可以使用相同的模式安装所需的任意数量的二进制文件。
|
||||
|
||||
如果之后添加了依赖其他二进制文件的新技能，您必须：
|
||||
|
||||
1. 更新 Dockerfile
|
||||
2. 重新构建镜像
|
||||
3. 重启容器
|
||||
|
||||
**示例 Dockerfile**
|
||||
|
||||
```dockerfile
|
||||
FROM node:22-bookworm
|
||||
|
||||
RUN apt-get update && apt-get install -y socat && rm -rf /var/lib/apt/lists/*
|
||||
|
||||
# 示例二进制文件 1：Gmail CLI
|
||||
RUN curl -L https://github.com/steipete/gog/releases/latest/download/gog_Linux_x86_64.tar.gz \
|
||||
| tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/gog
|
||||
|
||||
# 示例二进制文件 2：Google Places CLI
|
||||
RUN curl -L https://github.com/steipete/goplaces/releases/latest/download/goplaces_Linux_x86_64.tar.gz \
|
||||
| tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/goplaces
|
||||
|
||||
# 示例二进制文件 3：WhatsApp CLI
|
||||
RUN curl -L https://github.com/steipete/wacli/releases/latest/download/wacli_Linux_x86_64.tar.gz \
|
||||
| tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/wacli
|
||||
|
||||
# 使用相同模式在下方添加更多二进制文件
|
||||
|
||||
WORKDIR /app
|
||||
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
|
||||
COPY ui/package.json ./ui/package.json
|
||||
COPY scripts ./scripts
|
||||
|
||||
RUN corepack enable
|
||||
RUN pnpm install --frozen-lockfile
|
||||
|
||||
COPY . .
|
||||
RUN pnpm build
|
||||
RUN pnpm ui:install
|
||||
RUN pnpm ui:build
|
||||
|
||||
ENV NODE_ENV=production
|
||||
|
||||
CMD ["node","dist/index.js"]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 11）构建并启动
|
||||
|
||||
```bash
|
||||
docker compose build
|
||||
docker compose up -d openclaw-gateway
|
||||
```
|
||||
|
||||
验证二进制文件：
|
||||
|
||||
```bash
|
||||
docker compose exec openclaw-gateway which gog
|
||||
docker compose exec openclaw-gateway which goplaces
|
||||
docker compose exec openclaw-gateway which wacli
|
||||
```
|
||||
|
||||
预期输出：
|
||||
|
||||
```
|
||||
/usr/local/bin/gog
|
||||
/usr/local/bin/goplaces
|
||||
/usr/local/bin/wacli
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 12）验证 Gateway
|
||||
|
||||
```bash
|
||||
docker compose logs -f openclaw-gateway
|
||||
```
|
||||
|
||||
成功标志：
|
||||
|
||||
```
|
||||
[gateway] listening on ws://0.0.0.0:18789
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 13）从笔记本电脑访问
|
||||
|
||||
创建 SSH 隧道以转发 Gateway 端口：
|
||||
|
||||
```bash
|
||||
gcloud compute ssh openclaw-gateway --zone=us-central1-a -- -L 18789:127.0.0.1:18789
|
||||
```
|
||||
|
||||
在浏览器中打开：
|
||||
|
||||
`http://127.0.0.1:18789/`
|
||||
|
||||
粘贴您的 Gateway 令牌。
|
||||
|
||||
---
|
||||
|
||||
## 持久化存储位置（数据来源）
|
||||
|
||||
OpenClaw 在 Docker 中运行，但 Docker 并非数据来源。
|
||||
所有长期状态必须在重启、重建和重启动后仍然存在。
|
||||
|
||||
| 组件 | 位置 | 持久化机制 | 备注 |
|
||||
| -------------- | --------------------------------- | --------------- | --------------------------- |
|
||||
| Gateway 配置 | `/home/node/.openclaw/` | 宿主机卷挂载 | 包含 `openclaw.json`、令牌 |
|
||||
| 模型认证配置 | `/home/node/.openclaw/` | 宿主机卷挂载 | OAuth 令牌、API 密钥 |
|
||||
| 技能配置 | `/home/node/.openclaw/skills/` | 宿主机卷挂载 | 技能级别状态 |
|
||||
| 智能体工作区 | `/home/node/.openclaw/workspace/` | 宿主机卷挂载 | 代码和智能体产物 |
|
||||
| WhatsApp 会话 | `/home/node/.openclaw/` | 宿主机卷挂载 | 保留二维码登录 |
|
||||
| Gmail 密钥环 | `/home/node/.openclaw/` | 宿主机卷 + 密码 | 需要 `GOG_KEYRING_PASSWORD` |
|
||||
| 外部二进制文件 | `/usr/local/bin/` | Docker 镜像 | 必须在构建时内置 |
|
||||
| Node 运行时 | 容器文件系统 | Docker 镜像 | 每次镜像构建时重建 |
|
||||
| 操作系统软件包 | 容器文件系统 | Docker 镜像 | 请勿在运行时安装 |
|
||||
| Docker 容器 | 临时性 | 可重启 | 可安全销毁 |
|
||||
|
||||
---
|
||||
|
||||
## 更新
|
||||
|
||||
在虚拟机上更新 OpenClaw：
|
||||
|
||||
```bash
|
||||
cd ~/openclaw
|
||||
git pull
|
||||
docker compose build
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 故障排除
|
||||
|
||||
**SSH 连接被拒绝**
|
||||
|
||||
虚拟机创建后，SSH 密钥传播可能需要 1-2 分钟。请等待后重试。
|
||||
|
||||
**OS Login 问题**
|
||||
|
||||
检查您的 OS Login 配置：
|
||||
|
||||
```bash
|
||||
gcloud compute os-login describe-profile
|
||||
```
|
||||
|
||||
确保您的账户具有所需的 IAM 权限（Compute OS Login 或 Compute OS Admin Login）。
|
||||
|
||||
**内存不足 (OOM)**
|
||||
|
||||
如果使用 e2-micro 并遇到 OOM，请升级到 e2-small 或 e2-medium：
|
||||
|
||||
```bash
|
||||
# 先停止虚拟机
|
||||
gcloud compute instances stop openclaw-gateway --zone=us-central1-a
|
||||
|
||||
# 更改机器类型
|
||||
gcloud compute instances set-machine-type openclaw-gateway \
|
||||
--zone=us-central1-a \
|
||||
--machine-type=e2-small
|
||||
|
||||
# 启动虚拟机
|
||||
gcloud compute instances start openclaw-gateway --zone=us-central1-a
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 服务账户（安全最佳实践）
|
||||
|
||||
个人使用时，默认用户账户即可。
|
||||
|
||||
对于自动化或 CI/CD 流水线，请创建具有最小权限的专用服务账户：
|
||||
|
||||
1. 创建服务账户：
|
||||
|
||||
```bash
|
||||
gcloud iam service-accounts create openclaw-deploy \
|
||||
--display-name="OpenClaw Deployment"
|
||||
```
|
||||
|
||||
2. 授予 Compute Instance Admin 角色（或更精细的自定义角色）：
|
||||
```bash
|
||||
gcloud projects add-iam-policy-binding my-openclaw-project \
|
||||
--member="serviceAccount:openclaw-deploy@my-openclaw-project.iam.gserviceaccount.com" \
|
||||
--role="roles/compute.instanceAdmin.v1"
|
||||
```
|
||||
|
||||
避免在自动化中使用 Owner 角色。请遵循最小权限原则。
|
||||
|
||||
有关 IAM 角色详情，请参阅 https://cloud.google.com/iam/docs/understanding-roles。
|
||||
|
||||
---
|
||||
|
||||
## 后续步骤
|
||||
|
||||
- 设置消息渠道：[渠道](/channels)
|
||||
- 将本地设备配对为节点：[节点](/nodes)
|
||||
- 配置 Gateway：[Gateway 配置](/gateway/configuration)
|
||||
337
docs/zh-CN/platforms/hetzner.md
Normal file
337
docs/zh-CN/platforms/hetzner.md
Normal file
@@ -0,0 +1,337 @@
|
||||
---
|
||||
read_when:
|
||||
- 你希望 OpenClaw 在云端 VPS（而非笔记本电脑）上全天候运行
|
||||
- 你需要在自己的 VPS 上部署一个生产级、始终在线的 Gateway
|
||||
- 你希望完全掌控持久化、二进制文件和重启行为
|
||||
- 你正在 Hetzner 或类似提供商上通过 Docker 运行 OpenClaw
|
||||
summary: 在廉价的 Hetzner VPS 上通过 Docker 全天候运行 OpenClaw Gateway，支持持久化状态和内置二进制文件
|
||||
title: Hetzner
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T21:32:45Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: 84d9f24f1a803aa15faa52a05f25fe557ec3e2c2f48a00c701d49764bd3bc21a
|
||||
source_path: platforms/hetzner.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 在 Hetzner 上部署 OpenClaw（Docker 生产环境 VPS 指南）
|
||||
|
||||
## 目标
|
||||
|
||||
使用 Docker 在 Hetzner VPS 上运行持久化的 OpenClaw Gateway，支持持久化状态、内置二进制文件和安全的重启行为。
|
||||
|
||||
如果你想要"每月约 $5 实现 OpenClaw 全天候运行"，这是最简单可靠的方案。
|
||||
Hetzner 定价会变动；选择最小的 Debian/Ubuntu VPS，如果遇到内存不足（OOM）再扩容。
|
||||
|
||||
## 我们要做什么（简单说明）？
|
||||
|
||||
- 租一台小型 Linux 服务器（Hetzner VPS）
|
||||
- 安装 Docker（隔离的应用运行时）
|
||||
- 在 Docker 中启动 OpenClaw Gateway
|
||||
- 将 `~/.openclaw` + `~/.openclaw/workspace` 持久化到宿主机（重启/重建后数据不丢失）
|
||||
- 通过 SSH 隧道从笔记本电脑访问控制界面
|
||||
|
||||
Gateway 可通过以下方式访问：
|
||||
|
||||
- 从笔记本电脑进行 SSH 端口转发
|
||||
- 如果你自行管理防火墙和令牌，也可以直接暴露端口
|
||||
|
||||
本指南假设 Hetzner 上使用 Ubuntu 或 Debian。
|
||||
如果你使用其他 Linux VPS，请对应调整软件包。
|
||||
通用 Docker 流程请参阅 [Docker](/install/docker)。
|
||||
|
||||
---
|
||||
|
||||
## 快速路径（有经验的运维人员）
|
||||
|
||||
1. 创建 Hetzner VPS
|
||||
2. 安装 Docker
|
||||
3. 克隆 OpenClaw 仓库
|
||||
4. 创建持久化宿主机目录
|
||||
5. 配置 `.env` 和 `docker-compose.yml`
|
||||
6. 将所需二进制文件内置到镜像中
|
||||
7. `docker compose up -d`
|
||||
8. 验证持久化和 Gateway 访问
|
||||
|
||||
---
|
||||
|
||||
## 准备工作
|
||||
|
||||
- 拥有 root 权限的 Hetzner VPS
|
||||
- 从笔记本电脑可通过 SSH 访问
|
||||
- 基本熟悉 SSH + 复制/粘贴操作
|
||||
- 约 20 分钟时间
|
||||
- Docker 和 Docker Compose
|
||||
- 模型认证凭据
|
||||
- 可选的提供商凭据
|
||||
- WhatsApp 二维码
|
||||
- Telegram 机器人令牌
|
||||
- Gmail OAuth
|
||||
|
||||
---
|
||||
|
||||
## 1) 创建 VPS
|
||||
|
||||
在 Hetzner 创建一台 Ubuntu 或 Debian VPS。
|
||||
|
||||
以 root 身份连接：
|
||||
|
||||
```bash
|
||||
ssh root@YOUR_VPS_IP
|
||||
```
|
||||
|
||||
本指南假设 VPS 是有状态的。
|
||||
不要将其视为一次性基础设施。
|
||||
|
||||
---
|
||||
|
||||
## 2) 安装 Docker（在 VPS 上）
|
||||
|
||||
```bash
|
||||
apt-get update
|
||||
apt-get install -y git curl ca-certificates
|
||||
curl -fsSL https://get.docker.com | sh
|
||||
```
|
||||
|
||||
验证：
|
||||
|
||||
```bash
|
||||
docker --version
|
||||
docker compose version
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3) 克隆 OpenClaw 仓库
|
||||
|
||||
```bash
|
||||
git clone https://github.com/openclaw/openclaw.git
|
||||
cd openclaw
|
||||
```
|
||||
|
||||
本指南假设你将构建自定义镜像以确保二进制文件的持久化。
|
||||
|
||||
---
|
||||
|
||||
## 4) 创建持久化宿主机目录
|
||||
|
||||
Docker 容器是临时性的。
|
||||
所有长期状态必须存放在宿主机上。
|
||||
|
||||
```bash
|
||||
mkdir -p /root/.openclaw
|
||||
mkdir -p /root/.openclaw/workspace
|
||||
|
||||
# 将所有权设置为容器用户（uid 1000）：
|
||||
chown -R 1000:1000 /root/.openclaw
|
||||
chown -R 1000:1000 /root/.openclaw/workspace
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5) 配置环境变量
|
||||
|
||||
在仓库根目录创建 `.env` 文件。
|
||||
|
||||
```bash
|
||||
OPENCLAW_IMAGE=openclaw:latest
|
||||
OPENCLAW_GATEWAY_TOKEN=change-me-now
|
||||
OPENCLAW_GATEWAY_BIND=lan
|
||||
OPENCLAW_GATEWAY_PORT=18789
|
||||
|
||||
OPENCLAW_CONFIG_DIR=/root/.openclaw
|
||||
OPENCLAW_WORKSPACE_DIR=/root/.openclaw/workspace
|
||||
|
||||
GOG_KEYRING_PASSWORD=change-me-now
|
||||
XDG_CONFIG_HOME=/home/node/.openclaw
|
||||
```
|
||||
|
||||
生成强密钥：
|
||||
|
||||
```bash
|
||||
openssl rand -hex 32
|
||||
```
|
||||
|
||||
**请勿将此文件提交到版本控制。**
|
||||
|
||||
---
|
||||
|
||||
## 6) Docker Compose 配置
|
||||
|
||||
创建或更新 `docker-compose.yml`。
|
||||
|
||||
```yaml
|
||||
services:
|
||||
openclaw-gateway:
|
||||
image: ${OPENCLAW_IMAGE}
|
||||
build: .
|
||||
restart: unless-stopped
|
||||
env_file:
|
||||
- .env
|
||||
environment:
|
||||
- HOME=/home/node
|
||||
- NODE_ENV=production
|
||||
- TERM=xterm-256color
|
||||
- OPENCLAW_GATEWAY_BIND=${OPENCLAW_GATEWAY_BIND}
|
||||
- OPENCLAW_GATEWAY_PORT=${OPENCLAW_GATEWAY_PORT}
|
||||
- OPENCLAW_GATEWAY_TOKEN=${OPENCLAW_GATEWAY_TOKEN}
|
||||
- GOG_KEYRING_PASSWORD=${GOG_KEYRING_PASSWORD}
|
||||
- XDG_CONFIG_HOME=${XDG_CONFIG_HOME}
|
||||
- PATH=/home/linuxbrew/.linuxbrew/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
|
||||
volumes:
|
||||
- ${OPENCLAW_CONFIG_DIR}:/home/node/.openclaw
|
||||
- ${OPENCLAW_WORKSPACE_DIR}:/home/node/.openclaw/workspace
|
||||
ports:
|
||||
# 推荐：在 VPS 上仅绑定回环地址；通过 SSH 隧道访问。
|
||||
# 如需公开暴露，移除 `127.0.0.1:` 前缀并相应配置防火墙。
|
||||
- "127.0.0.1:${OPENCLAW_GATEWAY_PORT}:18789"
|
||||
|
||||
# 可选：仅在你需要将 iOS/Android 节点连接到此 VPS 且需要 Canvas 主机时使用。
|
||||
# 如果公开暴露此端口，请阅读 /gateway/security 并相应配置防火墙。
|
||||
# - "18793:18793"
|
||||
command:
|
||||
[
|
||||
"node",
|
||||
"dist/index.js",
|
||||
"gateway",
|
||||
"--bind",
|
||||
"${OPENCLAW_GATEWAY_BIND}",
|
||||
"--port",
|
||||
"${OPENCLAW_GATEWAY_PORT}",
|
||||
]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7) 将所需二进制文件内置到镜像中（关键步骤）
|
||||
|
||||
在运行中的容器内安装二进制文件是一个陷阱。
|
||||
任何在运行时安装的内容都会在重启后丢失。
|
||||
|
||||
技能所需的所有外部二进制文件必须在镜像构建时安装。
|
||||
|
||||
以下示例仅展示三个常见的二进制文件：
|
||||
|
||||
- `gog` 用于 Gmail 访问
|
||||
- `goplaces` 用于 Google Places
|
||||
- `wacli` 用于 WhatsApp
|
||||
|
||||
这些只是示例，并非完整列表。
|
||||
你可以使用相同的模式安装任意数量的二进制文件。
|
||||
|
||||
如果你后续添加了依赖额外二进制文件的新技能，你必须：
|
||||
|
||||
1. 更新 Dockerfile
|
||||
2. 重新构建镜像
|
||||
3. 重启容器
|
||||
|
||||
**示例 Dockerfile**
|
||||
|
||||
```dockerfile
|
||||
FROM node:22-bookworm
|
||||
|
||||
RUN apt-get update && apt-get install -y socat && rm -rf /var/lib/apt/lists/*
|
||||
|
||||
# 示例二进制文件 1：Gmail CLI
|
||||
RUN curl -L https://github.com/steipete/gog/releases/latest/download/gog_Linux_x86_64.tar.gz \
|
||||
| tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/gog
|
||||
|
||||
# 示例二进制文件 2：Google Places CLI
|
||||
RUN curl -L https://github.com/steipete/goplaces/releases/latest/download/goplaces_Linux_x86_64.tar.gz \
|
||||
| tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/goplaces
|
||||
|
||||
# 示例二进制文件 3：WhatsApp CLI
|
||||
RUN curl -L https://github.com/steipete/wacli/releases/latest/download/wacli_Linux_x86_64.tar.gz \
|
||||
| tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/wacli
|
||||
|
||||
# 在下方使用相同模式添加更多二进制文件
|
||||
|
||||
WORKDIR /app
|
||||
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
|
||||
COPY ui/package.json ./ui/package.json
|
||||
COPY scripts ./scripts
|
||||
|
||||
RUN corepack enable
|
||||
RUN pnpm install --frozen-lockfile
|
||||
|
||||
COPY . .
|
||||
RUN pnpm build
|
||||
RUN pnpm ui:install
|
||||
RUN pnpm ui:build
|
||||
|
||||
ENV NODE_ENV=production
|
||||
|
||||
CMD ["node","dist/index.js"]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8) 构建并启动
|
||||
|
||||
```bash
|
||||
docker compose build
|
||||
docker compose up -d openclaw-gateway
|
||||
```
|
||||
|
||||
验证二进制文件：
|
||||
|
||||
```bash
|
||||
docker compose exec openclaw-gateway which gog
|
||||
docker compose exec openclaw-gateway which goplaces
|
||||
docker compose exec openclaw-gateway which wacli
|
||||
```
|
||||
|
||||
预期输出：
|
||||
|
||||
```
|
||||
/usr/local/bin/gog
|
||||
/usr/local/bin/goplaces
|
||||
/usr/local/bin/wacli
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9) 验证 Gateway
|
||||
|
||||
```bash
|
||||
docker compose logs -f openclaw-gateway
|
||||
```
|
||||
|
||||
成功标志：
|
||||
|
||||
```
|
||||
[gateway] listening on ws://0.0.0.0:18789
|
||||
```
|
||||
|
||||
从笔记本电脑执行：
|
||||
|
||||
```bash
|
||||
ssh -N -L 18789:127.0.0.1:18789 root@YOUR_VPS_IP
|
||||
```
|
||||
|
||||
打开：
|
||||
|
||||
`http://127.0.0.1:18789/`
|
||||
|
||||
粘贴你的 Gateway 令牌。
|
||||
|
||||
---
|
||||
|
||||
## 持久化位置说明（数据源）
|
||||
|
||||
OpenClaw 在 Docker 中运行，但 Docker 不是数据源。
|
||||
所有长期状态必须能在重启、重建和重启后保留。
|
||||
|
||||
| 组件 | 位置 | 持久化机制 | 备注 |
|
||||
| -------------- | --------------------------------- | --------------- | --------------------------- |
|
||||
| Gateway 配置 | `/home/node/.openclaw/` | 宿主机卷挂载 | 包含 `openclaw.json`、令牌 |
|
||||
| 模型认证配置 | `/home/node/.openclaw/` | 宿主机卷挂载 | OAuth 令牌、API 密钥 |
|
||||
| 技能配置 | `/home/node/.openclaw/skills/` | 宿主机卷挂载 | 技能级别状态 |
|
||||
| 智能体工作区 | `/home/node/.openclaw/workspace/` | 宿主机卷挂载 | 代码和智能体产物 |
|
||||
| WhatsApp 会话 | `/home/node/.openclaw/` | 宿主机卷挂载 | 保留二维码登录状态 |
|
||||
| Gmail 密钥环 | `/home/node/.openclaw/` | 宿主机卷 + 密码 | 需要 `GOG_KEYRING_PASSWORD` |
|
||||
| 外部二进制文件 | `/usr/local/bin/` | Docker 镜像 | 必须在构建时内置 |
|
||||
| Node 运行时 | 容器文件系统 | Docker 镜像 | 每次构建镜像时重建 |
|
||||
| 操作系统软件包 | 容器文件系统 | Docker 镜像 | 不要在运行时安装 |
|
||||
| Docker 容器 | 临时性 | 可重启 | 可安全销毁 |
|
||||
60
docs/zh-CN/platforms/index.md
Normal file
60
docs/zh-CN/platforms/index.md
Normal file
@@ -0,0 +1,60 @@
|
||||
---
|
||||
read_when:
|
||||
- 查找操作系统支持或安装路径
|
||||
- 决定在哪里运行 Gateway
|
||||
summary: 平台支持概览（Gateway + 配套应用）
|
||||
title: 平台
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T21:32:17Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: 254852a5ed1996982a52eed4a72659477609e08d340c625d24ef6d99c21eece6
|
||||
source_path: platforms/index.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 平台
|
||||
|
||||
OpenClaw 核心使用 TypeScript 编写。**推荐使用 Node 作为运行时**。
|
||||
不建议在 Gateway 上使用 Bun（存在 WhatsApp/Telegram 相关的 bug）。
|
||||
|
||||
配套应用支持 macOS（菜单栏应用）和移动节点（iOS/Android）。Windows 和
|
||||
Linux 的配套应用已在规划中，但 Gateway 目前已完全支持。
|
||||
Windows 的原生配套应用同样在规划中；推荐通过 WSL2 使用 Gateway。
|
||||
|
||||
## 选择你的操作系统
|
||||
|
||||
- macOS：[macOS](/platforms/macos)
|
||||
- iOS：[iOS](/platforms/ios)
|
||||
- Android：[Android](/platforms/android)
|
||||
- Windows：[Windows](/platforms/windows)
|
||||
- Linux：[Linux](/platforms/linux)
|
||||
|
||||
## VPS 与托管
|
||||
|
||||
- VPS 中心：[VPS 托管](/vps)
|
||||
- Fly.io：[Fly.io](/platforms/fly)
|
||||
- Hetzner (Docker)：[Hetzner](/platforms/hetzner)
|
||||
- GCP (Compute Engine)：[GCP](/platforms/gcp)
|
||||
- exe.dev (VM + HTTPS 代理)：[exe.dev](/platforms/exe-dev)
|
||||
|
||||
## 常用链接
|
||||
|
||||
- 安装指南：[快速开始](/start/getting-started)
|
||||
- Gateway 运维手册：[Gateway](/gateway)
|
||||
- Gateway 配置：[配置](/gateway/configuration)
|
||||
- 服务状态：`openclaw gateway status`
|
||||
|
||||
## Gateway 服务安装（CLI）
|
||||
|
||||
使用以下任一方式（均受支持）：
|
||||
|
||||
- 向导（推荐）：`openclaw onboard --install-daemon`
|
||||
- 直接安装：`openclaw gateway install`
|
||||
- 配置流程：`openclaw configure` → 选择 **Gateway service**
|
||||
- 修复/迁移：`openclaw doctor`（会提示安装或修复服务）
|
||||
|
||||
服务目标取决于操作系统：
|
||||
|
||||
- macOS：LaunchAgent（`bot.molt.gateway` 或 `bot.molt.<profile>`；旧版 `com.openclaw.*`）
|
||||
- Linux/WSL2：systemd 用户服务（`openclaw-gateway[-<profile>].service`）
|
||||
114
docs/zh-CN/platforms/ios.md
Normal file
114
docs/zh-CN/platforms/ios.md
Normal file
@@ -0,0 +1,114 @@
|
||||
---
|
||||
read_when:
|
||||
- 配对或重新连接 iOS 节点
|
||||
- 从源码运行 iOS 应用
|
||||
- 调试 Gateway 发现或画布命令
|
||||
summary: iOS 节点应用：连接 Gateway、配对、画布及故障排除
|
||||
title: iOS 应用
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T21:32:23Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: 692eebdc82e4bb8dc221bcbabf6a344a861a839fc377f1aeeb6eecaa4917a232
|
||||
source_path: platforms/ios.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# iOS 应用（节点）
|
||||
|
||||
可用性：内部预览。iOS 应用尚未公开分发。
|
||||
|
||||
## 功能说明
|
||||
|
||||
- 通过 WebSocket 连接到 Gateway（局域网或 tailnet）。
|
||||
- 暴露节点能力：画布、屏幕快照、摄像头捕获、位置、对话模式、语音唤醒。
|
||||
- 接收 `node.invoke` 命令并上报节点状态事件。
|
||||
|
||||
## 要求
|
||||
|
||||
- Gateway 运行在另一台设备上（macOS、Linux 或通过 WSL2 的 Windows）。
|
||||
- 网络路径：
|
||||
- 通过 Bonjour 的同一局域网，**或**
|
||||
- 通过单播 DNS-SD 的 Tailnet（示例域名：`openclaw.internal.`），**或**
|
||||
- 手动输入主机/端口（备用方案）。
|
||||
|
||||
## 快速开始（配对 + 连接）
|
||||
|
||||
1. 启动 Gateway：
|
||||
|
||||
```bash
|
||||
openclaw gateway --port 18789
|
||||
```
|
||||
|
||||
2. 在 iOS 应用中，打开设置并选择已发现的 Gateway（或启用手动主机并输入主机/端口）。
|
||||
|
||||
3. 在 Gateway 主机上批准配对请求：
|
||||
|
||||
```bash
|
||||
openclaw nodes pending
|
||||
openclaw nodes approve <requestId>
|
||||
```
|
||||
|
||||
4. 验证连接：
|
||||
|
||||
```bash
|
||||
openclaw nodes status
|
||||
openclaw gateway call node.list --params "{}"
|
||||
```
|
||||
|
||||
## 发现路径
|
||||
|
||||
### Bonjour（局域网）
|
||||
|
||||
Gateway 在 `local.` 上广播 `_openclaw-gw._tcp`。iOS 应用会自动列出这些服务。
|
||||
|
||||
### Tailnet（跨网络）
|
||||
|
||||
如果 mDNS 被阻止，请使用单播 DNS-SD 区域（选择一个域名；示例：`openclaw.internal.`）和 Tailscale 分割 DNS。
|
||||
参阅 [Bonjour](/gateway/bonjour) 了解 CoreDNS 配置示例。
|
||||
|
||||
### 手动主机/端口
|
||||
|
||||
在设置中，启用**手动主机**并输入 Gateway 主机 + 端口（默认 `18789`）。
|
||||
|
||||
## 画布 + A2UI
|
||||
|
||||
iOS 节点渲染一个 WKWebView 画布。使用 `node.invoke` 来驱动它：
|
||||
|
||||
```bash
|
||||
openclaw nodes invoke --node "iOS Node" --command canvas.navigate --params '{"url":"http://<gateway-host>:18793/__openclaw__/canvas/"}'
|
||||
```
|
||||
|
||||
注意事项：
|
||||
|
||||
- Gateway 画布主机提供 `/__openclaw__/canvas/` 和 `/__openclaw__/a2ui/` 服务。
|
||||
- iOS 节点在连接时如果画布主机 URL 已广播，会自动导航到 A2UI。
|
||||
- 使用 `canvas.navigate` 和 `{"url":""}` 返回内置脚手架页面。
|
||||
|
||||
### 画布执行 / 快照
|
||||
|
||||
```bash
|
||||
openclaw nodes invoke --node "iOS Node" --command canvas.eval --params '{"javaScript":"(() => { const {ctx} = window.__openclaw; ctx.clearRect(0,0,innerWidth,innerHeight); ctx.lineWidth=6; ctx.strokeStyle=\"#ff2d55\"; ctx.beginPath(); ctx.moveTo(40,40); ctx.lineTo(innerWidth-40, innerHeight-40); ctx.stroke(); return \"ok\"; })()"}'
|
||||
```
|
||||
|
||||
```bash
|
||||
openclaw nodes invoke --node "iOS Node" --command canvas.snapshot --params '{"maxWidth":900,"format":"jpeg"}'
|
||||
```
|
||||
|
||||
## 语音唤醒 + 对话模式
|
||||
|
||||
- 语音唤醒和对话模式可在设置中配置。
|
||||
- iOS 可能会挂起后台音频；当应用不在前台时，请将语音功能视为尽力而为。
|
||||
|
||||
## 常见错误
|
||||
|
||||
- `NODE_BACKGROUND_UNAVAILABLE`：将 iOS 应用切换到前台（画布/摄像头/屏幕命令需要前台运行）。
|
||||
- `A2UI_HOST_NOT_CONFIGURED`：Gateway 未广播画布主机 URL；请检查 [Gateway 配置](/gateway/configuration) 中的 `canvasHost`。
|
||||
- 配对提示始终未出现：运行 `openclaw nodes pending` 并手动批准。
|
||||
- 重新安装后重连失败：钥匙串中的配对令牌已被清除；请重新配对节点。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [配对](/gateway/pairing)
|
||||
- [发现](/gateway/discovery)
|
||||
- [Bonjour](/gateway/bonjour)
|
||||
99
docs/zh-CN/platforms/linux.md
Normal file
99
docs/zh-CN/platforms/linux.md
Normal file
@@ -0,0 +1,99 @@
|
||||
---
|
||||
read_when:
|
||||
- 查找 Linux 伴侣应用状态
|
||||
- 规划平台覆盖范围或贡献
|
||||
summary: Linux 支持 + 伴侣应用状态
|
||||
title: Linux 应用
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T21:32:18Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: a9bbbcecf2fd522a2f5ac8f3b9068febbc43658465bfb9276bff6c3e946789d2
|
||||
source_path: platforms/linux.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Linux 应用
|
||||
|
||||
Gateway 在 Linux 上完全受支持。**推荐使用 Node 作为运行时**。
|
||||
不建议将 Bun 用于 Gateway（WhatsApp/Telegram 存在 bug）。
|
||||
|
||||
原生 Linux 伴侣应用已在计划中。如果您想帮助构建，欢迎贡献。
|
||||
|
||||
## 新手快速路径（VPS）
|
||||
|
||||
1. 安装 Node 22+
|
||||
2. `npm i -g openclaw@latest`
|
||||
3. `openclaw onboard --install-daemon`
|
||||
4. 从您的笔记本电脑：`ssh -N -L 18789:127.0.0.1:18789 <user>@<host>`
|
||||
5. 打开 `http://127.0.0.1:18789/` 并粘贴您的令牌
|
||||
|
||||
分步 VPS 指南：[exe.dev](/platforms/exe-dev)
|
||||
|
||||
## 安装
|
||||
|
||||
- [快速开始](/start/getting-started)
|
||||
- [安装与更新](/install/updating)
|
||||
- 可选流程：[Bun（实验性）](/install/bun)、[Nix](/install/nix)、[Docker](/install/docker)
|
||||
|
||||
## Gateway
|
||||
|
||||
- [Gateway 运维手册](/gateway)
|
||||
- [配置](/gateway/configuration)
|
||||
|
||||
## Gateway 服务安装（CLI）
|
||||
|
||||
使用以下任一方式：
|
||||
|
||||
```
|
||||
openclaw onboard --install-daemon
|
||||
```
|
||||
|
||||
或：
|
||||
|
||||
```
|
||||
openclaw gateway install
|
||||
```
|
||||
|
||||
或：
|
||||
|
||||
```
|
||||
openclaw configure
|
||||
```
|
||||
|
||||
出现提示时选择 **Gateway 服务**。
|
||||
|
||||
修复/迁移：
|
||||
|
||||
```
|
||||
openclaw doctor
|
||||
```
|
||||
|
||||
## 系统控制（systemd 用户单元）
|
||||
|
||||
OpenClaw 默认安装 systemd **用户**服务。对于共享或常驻服务器，请使用**系统**服务。完整的单元示例和指南请参阅 [Gateway 运维手册](/gateway)。
|
||||
|
||||
最小化设置：
|
||||
|
||||
创建 `~/.config/systemd/user/openclaw-gateway[-<profile>].service`：
|
||||
|
||||
```
|
||||
[Unit]
|
||||
Description=OpenClaw Gateway (profile: <profile>, v<version>)
|
||||
After=network-online.target
|
||||
Wants=network-online.target
|
||||
|
||||
[Service]
|
||||
ExecStart=/usr/local/bin/openclaw gateway --port 18789
|
||||
Restart=always
|
||||
RestartSec=5
|
||||
|
||||
[Install]
|
||||
WantedBy=default.target
|
||||
```
|
||||
|
||||
启用服务：
|
||||
|
||||
```
|
||||
systemctl --user enable --now openclaw-gateway[-<profile>].service
|
||||
```
|
||||
77
docs/zh-CN/platforms/mac/bundled-gateway.md
Normal file
77
docs/zh-CN/platforms/mac/bundled-gateway.md
Normal file
@@ -0,0 +1,77 @@
|
||||
---
|
||||
read_when:
|
||||
- 打包 OpenClaw.app
|
||||
- 调试 macOS gateway launchd 服务
|
||||
- 为 macOS 安装 gateway CLI
|
||||
summary: macOS 上的 Gateway 运行时（外部 launchd 服务）
|
||||
title: macOS 上的 Gateway
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T21:32:27Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: 4a3e963d13060b123538005439213e786e76127b370a6c834d85a369e4626fe5
|
||||
source_path: platforms/mac/bundled-gateway.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# macOS 上的 Gateway（外部 launchd）
|
||||
|
||||
OpenClaw.app 不再捆绑 Node/Bun 或 Gateway 运行时。macOS 应用
|
||||
要求**外部**安装 `openclaw` CLI，不会将 Gateway 作为子进程启动，而是管理一个
|
||||
按用户配置的 launchd 服务来保持 Gateway 运行（如果本地已有 Gateway 在运行，则会连接到现有实例）。
|
||||
|
||||
## 安装 CLI（本地模式必需）
|
||||
|
||||
Mac 上需要 Node 22+，然后全局安装 `openclaw`：
|
||||
|
||||
```bash
|
||||
npm install -g openclaw@<version>
|
||||
```
|
||||
|
||||
macOS 应用的 **Install CLI** 按钮通过 npm/pnpm 执行相同的安装流程（不建议使用 bun 作为 Gateway 运行时）。
|
||||
|
||||
## Launchd（Gateway 作为 LaunchAgent）
|
||||
|
||||
标签：
|
||||
|
||||
- `bot.molt.gateway`（或 `bot.molt.<profile>`；旧版 `com.openclaw.*` 可能仍然存在）
|
||||
|
||||
Plist 位置（按用户）：
|
||||
|
||||
- `~/Library/LaunchAgents/bot.molt.gateway.plist`
|
||||
（或 `~/Library/LaunchAgents/bot.molt.<profile>.plist`）
|
||||
|
||||
管理者：
|
||||
|
||||
- macOS 应用在本地模式下负责 LaunchAgent 的安装/更新。
|
||||
- CLI 也可以安装它：`openclaw gateway install`。
|
||||
|
||||
行为：
|
||||
|
||||
- "OpenClaw Active" 启用/禁用 LaunchAgent。
|
||||
- 退出应用**不会**停止 Gateway（launchd 会保持其运行）。
|
||||
- 如果配置端口上已有 Gateway 在运行，应用会连接到该实例，而不是启动新的。
|
||||
|
||||
日志：
|
||||
|
||||
- launchd 标准输出/错误：`/tmp/openclaw/openclaw-gateway.log`
|
||||
|
||||
## 版本兼容性
|
||||
|
||||
macOS 应用会将 Gateway 版本与自身版本进行比对。如果不兼容，请更新全局 CLI 以匹配应用版本。
|
||||
|
||||
## 冒烟测试
|
||||
|
||||
```bash
|
||||
openclaw --version
|
||||
|
||||
OPENCLAW_SKIP_CHANNELS=1 \
|
||||
OPENCLAW_SKIP_CANVAS_HOST=1 \
|
||||
openclaw gateway --port 18999 --bind loopback
|
||||
```
|
||||
|
||||
然后：
|
||||
|
||||
```bash
|
||||
openclaw gateway call health --url ws://127.0.0.1:18999 --timeout 3000
|
||||
```
|
||||
127
docs/zh-CN/platforms/mac/canvas.md
Normal file
127
docs/zh-CN/platforms/mac/canvas.md
Normal file
@@ -0,0 +1,127 @@
|
||||
---
|
||||
read_when:
|
||||
- 实现 macOS Canvas 面板
|
||||
- 为可视化工作区添加智能体控制
|
||||
- 调试 WKWebView canvas 加载问题
|
||||
summary: 智能体控制的 Canvas 面板，通过 WKWebView + 自定义 URL scheme 嵌入
|
||||
title: Canvas
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T21:32:34Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: e39caa21542e839d9f59ad0bf7ecefb379225ed7e8f00cd59131d188f193bec6
|
||||
source_path: platforms/mac/canvas.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Canvas（macOS 应用）
|
||||
|
||||
macOS 应用使用 `WKWebView` 嵌入了一个智能体控制的 **Canvas 面板**。它是一个轻量级的可视化工作区，用于 HTML/CSS/JS、A2UI 以及小型交互式 UI 界面。
|
||||
|
||||
## Canvas 的存储位置
|
||||
|
||||
Canvas 状态存储在 Application Support 目录下：
|
||||
|
||||
- `~/Library/Application Support/OpenClaw/canvas/<session>/...`
|
||||
|
||||
Canvas 面板通过**自定义 URL scheme** 提供这些文件：
|
||||
|
||||
- `openclaw-canvas://<session>/<path>`
|
||||
|
||||
示例：
|
||||
|
||||
- `openclaw-canvas://main/` → `<canvasRoot>/main/index.html`
|
||||
- `openclaw-canvas://main/assets/app.css` → `<canvasRoot>/main/assets/app.css`
|
||||
- `openclaw-canvas://main/widgets/todo/` → `<canvasRoot>/main/widgets/todo/index.html`
|
||||
|
||||
如果根目录下不存在 `index.html`，应用会显示一个**内置脚手架页面**。
|
||||
|
||||
## 面板行为
|
||||
|
||||
- 无边框、可调整大小的面板，锚定在菜单栏（或鼠标光标）附近。
|
||||
- 按会话记忆大小/位置。
|
||||
- 本地 canvas 文件变更时自动重新加载。
|
||||
- 同一时间只显示一个 Canvas 面板（根据需要切换会话）。
|
||||
|
||||
可以在设置 → **允许 Canvas** 中禁用 Canvas。禁用后，canvas 节点命令返回 `CANVAS_DISABLED`。
|
||||
|
||||
## 智能体 API 接口
|
||||
|
||||
Canvas 通过 **Gateway WebSocket** 暴露，因此智能体可以：
|
||||
|
||||
- 显示/隐藏面板
|
||||
- 导航到路径或 URL
|
||||
- 执行 JavaScript
|
||||
- 捕获快照图像
|
||||
|
||||
CLI 示例：
|
||||
|
||||
```bash
|
||||
openclaw nodes canvas present --node <id>
|
||||
openclaw nodes canvas navigate --node <id> --url "/"
|
||||
openclaw nodes canvas eval --node <id> --js "document.title"
|
||||
openclaw nodes canvas snapshot --node <id>
|
||||
```
|
||||
|
||||
注意事项：
|
||||
|
||||
- `canvas.navigate` 接受**本地 canvas 路径**、`http(s)` URL 和 `file://` URL。
|
||||
- 如果传入 `"/"`，Canvas 会显示本地脚手架或 `index.html`。
|
||||
|
||||
## Canvas 中的 A2UI
|
||||
|
||||
A2UI 由 Gateway canvas 主机托管，并在 Canvas 面板内渲染。当 Gateway 广播 Canvas 主机时，macOS 应用在首次打开时会自动导航到 A2UI 主机页面。
|
||||
|
||||
默认 A2UI 主机 URL：
|
||||
|
||||
```
|
||||
http://<gateway-host>:18793/__openclaw__/a2ui/
|
||||
```
|
||||
|
||||
### A2UI 命令（v0.8）
|
||||
|
||||
Canvas 当前接受 **A2UI v0.8** 服务端→客户端消息：
|
||||
|
||||
- `beginRendering`
|
||||
- `surfaceUpdate`
|
||||
- `dataModelUpdate`
|
||||
- `deleteSurface`
|
||||
|
||||
不支持 `createSurface`（v0.9）。
|
||||
|
||||
CLI 示例：
|
||||
|
||||
```bash
|
||||
cat > /tmp/a2ui-v0.8.jsonl <<'EOFA2'
|
||||
{"surfaceUpdate":{"surfaceId":"main","components":[{"id":"root","component":{"Column":{"children":{"explicitList":["title","content"]}}}},{"id":"title","component":{"Text":{"text":{"literalString":"Canvas (A2UI v0.8)"},"usageHint":"h1"}}},{"id":"content","component":{"Text":{"text":{"literalString":"If you can read this, A2UI push works."},"usageHint":"body"}}}]}}
|
||||
{"beginRendering":{"surfaceId":"main","root":"root"}}
|
||||
EOFA2
|
||||
|
||||
openclaw nodes canvas a2ui push --jsonl /tmp/a2ui-v0.8.jsonl --node <id>
|
||||
```
|
||||
|
||||
快速冒烟测试：
|
||||
|
||||
```bash
|
||||
openclaw nodes canvas a2ui push --node <id> --text "Hello from A2UI"
|
||||
```
|
||||
|
||||
## 从 Canvas 触发智能体运行
|
||||
|
||||
Canvas 可以通过深层链接触发新的智能体运行：
|
||||
|
||||
- `openclaw://agent?...`
|
||||
|
||||
示例（在 JS 中）：
|
||||
|
||||
```js
|
||||
window.location.href = "openclaw://agent?message=Review%20this%20design";
|
||||
```
|
||||
|
||||
除非提供有效密钥，否则应用会提示确认。
|
||||
|
||||
## 安全注意事项
|
||||
|
||||
- Canvas scheme 阻止目录遍历；文件必须位于会话根目录下。
|
||||
- 本地 Canvas 内容使用自定义 scheme（无需回环服务器）。
|
||||
- 仅在显式导航时才允许外部 `http(s)` URL。
|
||||
62
docs/zh-CN/platforms/mac/child-process.md
Normal file
62
docs/zh-CN/platforms/mac/child-process.md
Normal file
@@ -0,0 +1,62 @@
|
||||
---
|
||||
read_when:
|
||||
- 将 Mac 应用与 Gateway 生命周期集成
|
||||
summary: macOS 上的 Gateway 生命周期（launchd）
|
||||
title: Gateway 生命周期
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T21:32:36Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: 9b910f574b723bc194ac663a5168e48d95f55cb468ce34c595d8ca60d3463c6a
|
||||
source_path: platforms/mac/child-process.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# macOS 上的 Gateway 生命周期
|
||||
|
||||
macOS 应用默认**通过 launchd 管理 Gateway**，不会将 Gateway 作为子进程启动。它首先尝试连接到已在配置端口上运行的 Gateway；如果无法连接，则通过外部 `openclaw` CLI（无内嵌运行时）启用 launchd 服务。这为你提供了可靠的登录自启动和崩溃后自动重启。
|
||||
|
||||
子进程模式（由应用直接启动 Gateway）**目前未使用**。如果你需要与 UI 更紧密的耦合，请在终端中手动运行 Gateway。
|
||||
|
||||
## 默认行为（launchd）
|
||||
|
||||
- 应用安装一个标签为 `bot.molt.gateway` 的用户级 LaunchAgent（使用 `--profile`/`OPENCLAW_PROFILE` 时为 `bot.molt.<profile>`；兼容旧版 `com.openclaw.*`）。
|
||||
- 当启用本地模式时，应用会确保 LaunchAgent 已加载，并在需要时启动 Gateway。
|
||||
- 日志写入 launchd Gateway 日志路径（可在调试设置中查看）。
|
||||
|
||||
常用命令：
|
||||
|
||||
```bash
|
||||
launchctl kickstart -k gui/$UID/bot.molt.gateway
|
||||
launchctl bootout gui/$UID/bot.molt.gateway
|
||||
```
|
||||
|
||||
运行命名配置文件时，请将标签替换为 `bot.molt.<profile>`。
|
||||
|
||||
## 未签名的开发构建
|
||||
|
||||
`scripts/restart-mac.sh --no-sign` 用于在没有签名密钥时进行快速本地构建。为防止 launchd 指向未签名的中继二进制文件，它会：
|
||||
|
||||
- 写入 `~/.openclaw/disable-launchagent`。
|
||||
|
||||
已签名的 `scripts/restart-mac.sh` 运行会在检测到该标记文件时清除此覆盖。手动重置方法：
|
||||
|
||||
```bash
|
||||
rm ~/.openclaw/disable-launchagent
|
||||
```
|
||||
|
||||
## 仅连接模式
|
||||
|
||||
要强制 macOS 应用**永不安装或管理 launchd**，请使用 `--attach-only`（或 `--no-launchd`）启动。这会设置 `~/.openclaw/disable-launchagent`，使应用仅连接到已运行的 Gateway。你也可以在调试设置中切换相同的行为。
|
||||
|
||||
## 远程模式
|
||||
|
||||
远程模式不会启动本地 Gateway。应用使用 SSH 隧道连接到远程主机，并通过该隧道进行通信。
|
||||
|
||||
## 为何优先选择 launchd
|
||||
|
||||
- 登录时自动启动。
|
||||
- 内置重启/KeepAlive 语义。
|
||||
- 可预测的日志和进程监管。
|
||||
|
||||
如果将来再次需要真正的子进程模式，应将其作为独立的、明确的开发专用模式进行文档记录。
|
||||
109
docs/zh-CN/platforms/mac/dev-setup.md
Normal file
109
docs/zh-CN/platforms/mac/dev-setup.md
Normal file
@@ -0,0 +1,109 @@
|
||||
---
|
||||
read_when:
|
||||
- 设置 macOS 开发环境
|
||||
summary: 面向 OpenClaw macOS 应用开发者的设置指南
|
||||
title: macOS 开发环境设置
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T21:32:41Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: 4ea67701bd58b7512f945fce58d79e1b3d990fbf45183323a1e3ab9688827623
|
||||
source_path: platforms/mac/dev-setup.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# macOS 开发者设置
|
||||
|
||||
本指南介绍从源代码构建和运行 OpenClaw macOS 应用的必要步骤。
|
||||
|
||||
## 前提条件
|
||||
|
||||
在构建应用之前，请确保已安装以下内容：
|
||||
|
||||
1. **Xcode 26.2+**：Swift 开发所需。
|
||||
2. **Node.js 22+ & pnpm**：Gateway、CLI 和打包脚本所需。
|
||||
|
||||
## 1. 安装依赖
|
||||
|
||||
安装项目的全部依赖：
|
||||
|
||||
```bash
|
||||
pnpm install
|
||||
```
|
||||
|
||||
## 2. 构建和打包应用
|
||||
|
||||
要构建 macOS 应用并将其打包为 `dist/OpenClaw.app`，请运行：
|
||||
|
||||
```bash
|
||||
./scripts/package-mac-app.sh
|
||||
```
|
||||
|
||||
如果你没有 Apple Developer ID 证书，脚本将自动使用**临时签名**（`-`）。
|
||||
|
||||
有关开发运行模式、签名选项和 Team ID 故障排除，请参阅 macOS 应用 README：
|
||||
https://github.com/openclaw/openclaw/blob/main/apps/macos/README.md
|
||||
|
||||
> **注意**：临时签名的应用可能会触发安全提示。如果应用立即崩溃并显示 "Abort trap 6"，请参阅[故障排除](#troubleshooting)部分。
|
||||
|
||||
## 3. 安装 CLI
|
||||
|
||||
macOS 应用需要全局安装 `openclaw` CLI 来管理后台任务。
|
||||
|
||||
**安装方式（推荐）：**
|
||||
|
||||
1. 打开 OpenClaw 应用。
|
||||
2. 进入 **General** 设置选项卡。
|
||||
3. 点击 **"Install CLI"**。
|
||||
|
||||
或者手动安装：
|
||||
|
||||
```bash
|
||||
npm install -g openclaw@<version>
|
||||
```
|
||||
|
||||
## 故障排除
|
||||
|
||||
### 构建失败：工具链或 SDK 不匹配
|
||||
|
||||
macOS 应用构建需要最新的 macOS SDK 和 Swift 6.2 工具链。
|
||||
|
||||
**系统依赖（必需）：**
|
||||
|
||||
- **软件更新中可用的最新 macOS 版本**（Xcode 26.2 SDK 要求）
|
||||
- **Xcode 26.2**（Swift 6.2 工具链）
|
||||
|
||||
**检查：**
|
||||
|
||||
```bash
|
||||
xcodebuild -version
|
||||
xcrun swift --version
|
||||
```
|
||||
|
||||
如果版本不匹配，请更新 macOS/Xcode 并重新运行构建。
|
||||
|
||||
### 授权时应用崩溃
|
||||
|
||||
如果在尝试允许**语音识别**或**麦克风**访问时应用崩溃，可能是由于 TCC 缓存损坏或签名不匹配。
|
||||
|
||||
**修复方法：**
|
||||
|
||||
1. 重置 TCC 权限：
|
||||
```bash
|
||||
tccutil reset All bot.molt.mac.debug
|
||||
```
|
||||
2. 如果仍然无效，在 [`scripts/package-mac-app.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/package-mac-app.sh) 中临时更改 `BUNDLE_ID`，以强制 macOS 使用"全新状态"。
|
||||
|
||||
### Gateway 持续显示"Starting..."
|
||||
|
||||
如果 Gateway 状态一直停留在"Starting..."，请检查是否有僵尸进程占用了端口：
|
||||
|
||||
```bash
|
||||
openclaw gateway status
|
||||
openclaw gateway stop
|
||||
|
||||
# 如果你没有使用 LaunchAgent（开发模式/手动运行），查找监听进程：
|
||||
lsof -nP -iTCP:18789 -sTCP:LISTEN
|
||||
```
|
||||
|
||||
如果是手动运行的进程占用了端口，请停止该进程（Ctrl+C）。作为最后手段，终止上面找到的 PID。
|
||||
41
docs/zh-CN/platforms/mac/health.md
Normal file
41
docs/zh-CN/platforms/mac/health.md
Normal file
@@ -0,0 +1,41 @@
|
||||
---
|
||||
read_when:
|
||||
- 调试 Mac 应用健康指示器
|
||||
summary: macOS 应用如何报告 Gateway/Baileys 健康状态
|
||||
title: 健康检查
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T21:32:43Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: 0560e96501ddf53a499f8960cfcf11c2622fcb9056bfd1bcc57876e955cab03d
|
||||
source_path: platforms/mac/health.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# macOS 上的健康检查
|
||||
|
||||
如何从菜单栏应用查看已关联渠道的健康状态。
|
||||
|
||||
## 菜单栏
|
||||
|
||||
- 状态圆点现在反映 Baileys 健康状态：
|
||||
- 绿色：已关联 + socket 近期已打开。
|
||||
- 橙色：正在连接/重试中。
|
||||
- 红色：已登出或探测失败。
|
||||
- 次要行显示 "linked · auth 12m" 或显示失败原因。
|
||||
- "运行健康检查" 菜单项可触发按需探测。
|
||||
|
||||
## 设置
|
||||
|
||||
- 通用选项卡新增健康卡片，显示：已关联认证时长、会话存储路径/数量、上次检查时间、上次错误/状态码，以及"运行健康检查"/"显示日志"按钮。
|
||||
- 使用缓存快照，使 UI 即时加载，离线时优雅降级。
|
||||
- **渠道选项卡**展示渠道状态 + WhatsApp/Telegram 的控制项（登录二维码、登出、探测、上次断连/错误）。
|
||||
|
||||
## 探测工作原理
|
||||
|
||||
- 应用每约 60 秒以及按需通过 `ShellExecutor` 运行 `openclaw health --json`。探测会加载凭据并报告状态，不会发送消息。
|
||||
- 分别缓存上次成功的快照和上次错误，以避免闪烁；显示各自的时间戳。
|
||||
|
||||
## 不确定时
|
||||
|
||||
- 您仍然可以使用 [Gateway 健康检查](/gateway/health) 中的 CLI 流程（`openclaw status`、`openclaw status --deep`、`openclaw health --json`），并跟踪 `/tmp/openclaw/openclaw-*.log` 中的 `web-heartbeat` / `web-reconnect`。
|
||||
38
docs/zh-CN/platforms/mac/icon.md
Normal file
38
docs/zh-CN/platforms/mac/icon.md
Normal file
@@ -0,0 +1,38 @@
|
||||
---
|
||||
read_when:
|
||||
- 更改菜单栏图标行为
|
||||
summary: macOS 上 OpenClaw 菜单栏图标的状态和动画
|
||||
title: 菜单栏图标
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T21:32:49Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: a67a6e6bbdc2b611ba365d3be3dd83f9e24025d02366bc35ffcce9f0b121872b
|
||||
source_path: platforms/mac/icon.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 菜单栏图标状态
|
||||
|
||||
作者：steipete · 更新时间：2025-12-06 · 范围：macOS 应用（`apps/macos`）
|
||||
|
||||
- **空闲：** 正常图标动画（眨眼、偶尔摆动）。
|
||||
- **暂停：** 状态项使用 `appearsDisabled`；无动画。
|
||||
- **语音触发（大耳朵）：** 语音唤醒检测器在听到唤醒词时调用 `AppState.triggerVoiceEars(ttl: nil)`，在捕获语音期间保持 `earBoostActive=true`。耳朵放大（1.9 倍），显示圆形耳孔以提高可读性，然后在 1 秒静音后通过 `stopVoiceEars()` 恢复。仅由应用内语音管道触发。
|
||||
- **工作中（智能体运行中）：** `AppState.isWorking=true` 驱动"尾巴/腿部快速摆动"微动画：工作进行中腿部摆动加快并略有偏移。目前在 WebChat 智能体运行时切换；在接入其他长时间任务时请添加相同的切换逻辑。
|
||||
|
||||
接入点
|
||||
|
||||
- 语音唤醒：运行时/测试器在触发时调用 `AppState.triggerVoiceEars(ttl: nil)`，在 1 秒静音后调用 `stopVoiceEars()` 以匹配捕获窗口。
|
||||
- 智能体活动：在工作区间前后设置 `AppStateStore.shared.setWorking(true/false)`（已在 WebChat 智能体调用中完成）。保持区间简短，并在 `defer` 块中重置以避免动画卡住。
|
||||
|
||||
形状与尺寸
|
||||
|
||||
- 基础图标在 `CritterIconRenderer.makeIcon(blink:legWiggle:earWiggle:earScale:earHoles:)` 中绘制。
|
||||
- 耳朵缩放默认为 `1.0`；语音增强时设置 `earScale=1.9` 并切换 `earHoles=true`，不改变整体框架（18×18 pt 模板图像渲染到 36×36 px Retina 后备存储）。
|
||||
- 快速摆动使用最高约 1.0 的腿部摆幅并带有轻微的水平抖动；它与现有的空闲摆动叠加。
|
||||
|
||||
行为说明
|
||||
|
||||
- 耳朵/工作状态没有外部 CLI/代理切换；保持仅由应用自身信号控制，以避免意外的状态抖动。
|
||||
- 保持 TTL 较短（<10 秒），以便在任务挂起时图标能快速恢复到基准状态。
|
||||
64
docs/zh-CN/platforms/mac/logging.md
Normal file
64
docs/zh-CN/platforms/mac/logging.md
Normal file
@@ -0,0 +1,64 @@
|
||||
---
|
||||
read_when:
|
||||
- 捕获 macOS 日志或调查隐私数据日志记录
|
||||
- 调试语音唤醒/会话生命周期问题
|
||||
summary: OpenClaw 日志：滚动诊断文件日志 + 统一日志隐私标志
|
||||
title: macOS 日志
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T21:32:54Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: c4c201d154915e0eb08bf5e32bac98fa93766f50f2a24bf56ab4424eb7781526
|
||||
source_path: platforms/mac/logging.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 日志（macOS）
|
||||
|
||||
## 滚动诊断文件日志（Debug 面板）
|
||||
|
||||
OpenClaw 通过 swift-log（默认使用统一日志）路由 macOS 应用日志，并且在需要持久化捕获时可以将本地轮转文件日志写入磁盘。
|
||||
|
||||
- 详细级别：**Debug 面板 → Logs → App logging → Verbosity**
|
||||
- 启用：**Debug 面板 → Logs → App logging → "Write rolling diagnostics log (JSONL)"**
|
||||
- 位置：`~/Library/Logs/OpenClaw/diagnostics.jsonl`（自动轮转；旧文件以 `.1`、`.2`、… 为后缀）
|
||||
- 清除：**Debug 面板 → Logs → App logging → "Clear"**
|
||||
|
||||
注意事项：
|
||||
|
||||
- 此功能**默认关闭**。仅在主动调试时启用。
|
||||
- 该文件包含敏感信息；分享前请先审查内容。
|
||||
|
||||
## macOS 上统一日志的隐私数据
|
||||
|
||||
统一日志会屏蔽大部分负载内容，除非子系统选择启用 `privacy -off`。根据 Peter 关于 macOS [日志隐私机制](https://steipete.me/posts/2025/logging-privacy-shenanigans)（2025）的文章，这通过 `/Library/Preferences/Logging/Subsystems/` 中以子系统名称为键的 plist 文件来控制。只有新的日志条目才会应用该标志，因此请在复现问题之前启用它。
|
||||
|
||||
## 为 OpenClaw 启用（`bot.molt`）
|
||||
|
||||
- 先将 plist 写入临时文件，然后以 root 身份原子性地安装：
|
||||
|
||||
```bash
|
||||
cat <<'EOF' >/tmp/bot.molt.plist
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
|
||||
<plist version="1.0">
|
||||
<dict>
|
||||
<key>DEFAULT-OPTIONS</key>
|
||||
<dict>
|
||||
<key>Enable-Private-Data</key>
|
||||
<true/>
|
||||
</dict>
|
||||
</dict>
|
||||
</plist>
|
||||
EOF
|
||||
sudo install -m 644 -o root -g wheel /tmp/bot.molt.plist /Library/Preferences/Logging/Subsystems/bot.molt.plist
|
||||
```
|
||||
|
||||
- 无需重启；logd 会很快检测到该文件，但只有新的日志行才会包含隐私负载。
|
||||
- 使用现有的辅助脚本查看更丰富的输出，例如 `./scripts/clawlog.sh --category WebChat --last 5m`。
|
||||
|
||||
## 调试后禁用
|
||||
|
||||
- 移除覆盖配置：`sudo rm /Library/Preferences/Logging/Subsystems/bot.molt.plist`。
|
||||
- 可选择运行 `sudo log config --reload` 强制 logd 立即丢弃覆盖配置。
|
||||
- 请注意此数据可能包含电话号码和消息正文；仅在确实需要额外详细信息时才保留该 plist 文件。
|
||||
88
docs/zh-CN/platforms/mac/menu-bar.md
Normal file
88
docs/zh-CN/platforms/mac/menu-bar.md
Normal file
@@ -0,0 +1,88 @@
|
||||
---
|
||||
read_when:
|
||||
- 调整 Mac 菜单 UI 或状态逻辑
|
||||
summary: 菜单栏状态逻辑及向用户展示的内容
|
||||
title: 菜单栏
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T21:33:00Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: 8eb73c0e671a76aae4ebb653c65147610bf3e6d3c9c0943d150e292e7761d16d
|
||||
source_path: platforms/mac/menu-bar.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 菜单栏状态逻辑
|
||||
|
||||
## 显示内容
|
||||
|
||||
- 我们在菜单栏图标和菜单的第一行状态行中展示当前智能体的工作状态。
|
||||
- 工作活跃时隐藏健康状态；当所有会话空闲时恢复显示。
|
||||
- 菜单中的"节点"区块仅列出**设备**（通过 `node.list` 配对的节点），不包括客户端/在线状态条目。
|
||||
- 当提供商用量快照可用时，"用量"部分会显示在上下文下方。
|
||||
|
||||
## 状态模型
|
||||
|
||||
- 会话：事件携带 `runId`（每次运行）以及载荷中的 `sessionKey`。"main" 会话的键为 `main`；如果不存在，则回退到最近更新的会话。
|
||||
- 优先级：main 始终优先。如果 main 处于活跃状态，立即显示其状态。如果 main 空闲，则显示最近活跃的非 main 会话。活动进行中不会来回切换；仅在当前会话进入空闲或 main 变为活跃时才切换。
|
||||
- 活动类型：
|
||||
- `job`：高层命令执行（`state: started|streaming|done|error`）。
|
||||
- `tool`：`phase: start|result`，包含 `toolName` 和 `meta/args`。
|
||||
|
||||
## IconState 枚举（Swift）
|
||||
|
||||
- `idle`
|
||||
- `workingMain(ActivityKind)`
|
||||
- `workingOther(ActivityKind)`
|
||||
- `overridden(ActivityKind)`（调试覆盖）
|
||||
|
||||
### ActivityKind → 图标符号
|
||||
|
||||
- `exec` → 💻
|
||||
- `read` → 📄
|
||||
- `write` → ✍️
|
||||
- `edit` → 📝
|
||||
- `attach` → 📎
|
||||
- 默认 → 🛠️
|
||||
|
||||
### 视觉映射
|
||||
|
||||
- `idle`：正常小动物图标。
|
||||
- `workingMain`：带图标符号的徽章，完整色调，腿部"工作"动画。
|
||||
- `workingOther`：带图标符号的徽章，柔和色调，无快跑动画。
|
||||
- `overridden`：无论活动状态如何，使用所选的图标符号/色调。
|
||||
|
||||
## 状态行文本（菜单）
|
||||
|
||||
- 工作活跃时：`<会话角色> · <活动标签>`
|
||||
- 示例：`Main · exec: pnpm test`、`Other · read: apps/macos/Sources/OpenClaw/AppState.swift`。
|
||||
- 空闲时：回退显示健康摘要。
|
||||
|
||||
## 事件接收
|
||||
|
||||
- 来源：控制渠道 `agent` 事件（`ControlChannel.handleAgentEvent`）。
|
||||
- 解析字段：
|
||||
- `stream: "job"`，包含 `data.state` 用于启动/停止。
|
||||
- `stream: "tool"`，包含 `data.phase`、`name`，可选 `meta`/`args`。
|
||||
- 标签：
|
||||
- `exec`：`args.command` 的第一行。
|
||||
- `read`/`write`：缩短的路径。
|
||||
- `edit`：路径加上从 `meta`/diff 计数推断的变更类型。
|
||||
- 回退：工具名称。
|
||||
|
||||
## 调试覆盖
|
||||
|
||||
- 设置 ▸ 调试 ▸ "图标覆盖" 选择器：
|
||||
- `系统（自动）`（默认）
|
||||
- `工作中：main`（按工具类型）
|
||||
- `工作中：other`（按工具类型）
|
||||
- `空闲`
|
||||
- 通过 `@AppStorage("iconOverride")` 存储；映射到 `IconState.overridden`。
|
||||
|
||||
## 测试清单
|
||||
|
||||
- 触发 main 会话任务：验证图标立即切换且状态行显示 main 标签。
|
||||
- main 空闲时触发非 main 会话任务：图标/状态显示非 main；保持稳定直到完成。
|
||||
- 在 other 活跃时启动 main：图标立即切换到 main。
|
||||
- 快速连续工具调用：确保徽章不会闪烁（工具结果的 TTL 宽限期）。
|
||||
- 所有会话空闲后健康行重新出现。
|
||||
62
docs/zh-CN/platforms/mac/peekaboo.md
Normal file
62
docs/zh-CN/platforms/mac/peekaboo.md
Normal file
@@ -0,0 +1,62 @@
|
||||
---
|
||||
read_when:
|
||||
- 在 OpenClaw.app 中托管 PeekabooBridge
|
||||
- 通过 Swift Package Manager 集成 Peekaboo
|
||||
- 更改 PeekabooBridge 协议/路径
|
||||
summary: 用于 macOS UI 自动化的 PeekabooBridge 集成
|
||||
title: Peekaboo Bridge
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T21:32:57Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: b5b9ddb9a7c59e153a1d5d23c33616bb1542b5c7dadedc3af340aeee9ba03487
|
||||
source_path: platforms/mac/peekaboo.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Peekaboo Bridge（macOS UI 自动化）
|
||||
|
||||
OpenClaw 可以将 **PeekabooBridge** 作为本地的、权限感知的 UI 自动化代理进行托管。这使得 `peekaboo` CLI 能够驱动 UI 自动化，同时复用 macOS 应用的 TCC 权限。
|
||||
|
||||
## 这是什么（以及不是什么）
|
||||
|
||||
- **宿主**：OpenClaw.app 可以作为 PeekabooBridge 宿主。
|
||||
- **客户端**：使用 `peekaboo` CLI（无需单独的 `openclaw ui ...` 界面）。
|
||||
- **界面**：视觉叠加层保留在 Peekaboo.app 中；OpenClaw 只是一个轻量代理宿主。
|
||||
|
||||
## 启用桥接
|
||||
|
||||
在 macOS 应用中：
|
||||
|
||||
- 设置 → **启用 Peekaboo Bridge**
|
||||
|
||||
启用后，OpenClaw 会启动一个本地 UNIX 套接字服务器。如果禁用，宿主会停止，`peekaboo` 将回退到其他可用宿主。
|
||||
|
||||
## 客户端发现顺序
|
||||
|
||||
Peekaboo 客户端通常按以下顺序尝试宿主：
|
||||
|
||||
1. Peekaboo.app（完整用户体验）
|
||||
2. Claude.app（如已安装）
|
||||
3. OpenClaw.app（轻量代理）
|
||||
|
||||
使用 `peekaboo bridge status --verbose` 查看当前活跃的宿主及使用的套接字路径。你可以通过以下方式覆盖：
|
||||
|
||||
```bash
|
||||
export PEEKABOO_BRIDGE_SOCKET=/path/to/bridge.sock
|
||||
```
|
||||
|
||||
## 安全与权限
|
||||
|
||||
- 桥接会验证**调用方的代码签名**；强制执行 TeamID 白名单（Peekaboo 宿主 TeamID + OpenClaw 应用 TeamID）。
|
||||
- 请求在约 10 秒后超时。
|
||||
- 如果缺少所需权限，桥接会返回清晰的错误信息，而不是启动系统设置。
|
||||
|
||||
## 快照行为（自动化）
|
||||
|
||||
快照存储在内存中，并在短暂窗口期后自动过期。如果需要更长的保留时间，请从客户端重新捕获。
|
||||
|
||||
## 故障排除
|
||||
|
||||
- 如果 `peekaboo` 报告"bridge client is not authorized"，请确保客户端已正确签名，或仅在**调试**模式下使用 `PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1` 运行宿主。
|
||||
- 如果未找到宿主，请打开其中一个宿主应用（Peekaboo.app 或 OpenClaw.app）并确认已授予权限。
|
||||
46
docs/zh-CN/platforms/mac/permissions.md
Normal file
46
docs/zh-CN/platforms/mac/permissions.md
Normal file
@@ -0,0 +1,46 @@
|
||||
---
|
||||
read_when:
|
||||
- 调试缺失或卡住的 macOS 权限提示
|
||||
- 打包或签名 macOS 应用
|
||||
- 更改 Bundle ID 或应用安装路径
|
||||
summary: macOS 权限持久化（TCC）和签名要求
|
||||
title: macOS 权限
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T21:32:58Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: d012589c0583dd0b3792d695f3f71a6ff265704cf02a3b79f8c4a5b14712e6aa
|
||||
source_path: platforms/mac/permissions.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# macOS 权限（TCC）
|
||||
|
||||
macOS 权限授予是脆弱的。TCC 将权限授予与应用的代码签名、Bundle 标识符和磁盘路径关联。如果其中任何一项发生变化，macOS 会将该应用视为新应用，可能会丢弃或隐藏权限提示。
|
||||
|
||||
## 稳定权限的要求
|
||||
|
||||
- 相同路径：从固定位置运行应用（对于 OpenClaw，为 `dist/OpenClaw.app`）。
|
||||
- 相同 Bundle 标识符：更改 Bundle ID 会创建新的权限身份。
|
||||
- 已签名的应用：未签名或临时签名的构建不会持久化权限。
|
||||
- 一致的签名：使用真实的 Apple Development 或 Developer ID 证书，以确保签名在多次构建之间保持稳定。
|
||||
|
||||
临时签名每次构建都会生成新的身份。macOS 会忘记之前的授权，提示可能完全消失，直到清除过期条目为止。
|
||||
|
||||
## 权限提示消失时的恢复清单
|
||||
|
||||
1. 退出应用。
|
||||
2. 在系统设置 -> 隐私与安全性中移除该应用条目。
|
||||
3. 从相同路径重新启动应用并重新授予权限。
|
||||
4. 如果提示仍未出现，使用 `tccutil` 重置 TCC 条目后重试。
|
||||
5. 某些权限仅在完全重启 macOS 后才会重新出现。
|
||||
|
||||
重置示例（根据需要替换 Bundle ID）：
|
||||
|
||||
```bash
|
||||
sudo tccutil reset Accessibility bot.molt.mac
|
||||
sudo tccutil reset ScreenCapture bot.molt.mac
|
||||
sudo tccutil reset AppleEvents
|
||||
```
|
||||
|
||||
如果你正在测试权限，请始终使用真实证书签名。临时签名的构建仅适用于不需要权限的快速本地运行。
|
||||
92
docs/zh-CN/platforms/mac/release.md
Normal file
92
docs/zh-CN/platforms/mac/release.md
Normal file
@@ -0,0 +1,92 @@
|
||||
---
|
||||
read_when:
|
||||
- 制作或验证 OpenClaw macOS 发布版本
|
||||
- 更新 Sparkle appcast 或订阅源资源
|
||||
summary: OpenClaw macOS 发布清单（Sparkle 订阅源、打包、签名）
|
||||
title: macOS 发布
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T21:33:17Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: 703c08c13793cd8c96bd4c31fb4904cdf4ffff35576e7ea48a362560d371cb30
|
||||
source_path: platforms/mac/release.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# OpenClaw macOS 发布（Sparkle）
|
||||
|
||||
本应用现已支持 Sparkle 自动更新。发布构建必须经过 Developer ID 签名、压缩，并发布包含签名的 appcast 条目。
|
||||
|
||||
## 前提条件
|
||||
|
||||
- 已安装 Developer ID Application 证书（示例：`Developer ID Application: <Developer Name> (<TEAMID>)`）。
|
||||
- 环境变量 `SPARKLE_PRIVATE_KEY_FILE` 已设置为 Sparkle ed25519 私钥路径（公钥已嵌入 Info.plist）。如果缺失，请检查 `~/.profile`。
|
||||
- 用于 `xcrun notarytool` 的公证凭据（钥匙串配置文件或 API 密钥），以实现通过 Gatekeeper 安全分发的 DMG/zip。
|
||||
- 我们使用名为 `openclaw-notary` 的钥匙串配置文件，由 shell 配置文件中的 App Store Connect API 密钥环境变量创建：
|
||||
- `APP_STORE_CONNECT_API_KEY_P8`、`APP_STORE_CONNECT_KEY_ID`、`APP_STORE_CONNECT_ISSUER_ID`
|
||||
- `echo "$APP_STORE_CONNECT_API_KEY_P8" | sed 's/\\n/\n/g' > /tmp/openclaw-notary.p8`
|
||||
- `xcrun notarytool store-credentials "openclaw-notary" --key /tmp/openclaw-notary.p8 --key-id "$APP_STORE_CONNECT_KEY_ID" --issuer "$APP_STORE_CONNECT_ISSUER_ID"`
|
||||
- 已安装 `pnpm` 依赖（`pnpm install --config.node-linker=hoisted`）。
|
||||
- Sparkle 工具通过 SwiftPM 自动获取，位于 `apps/macos/.build/artifacts/sparkle/Sparkle/bin/`（`sign_update`、`generate_appcast` 等）。
|
||||
|
||||
## 构建与打包
|
||||
|
||||
注意事项：
|
||||
|
||||
- `APP_BUILD` 映射到 `CFBundleVersion`/`sparkle:version`；保持纯数字且单调递增（不含 `-beta`），否则 Sparkle 会将其视为相同版本。
|
||||
- 默认为当前架构（`$(uname -m)`）。对于发布/通用构建，设置 `BUILD_ARCHS="arm64 x86_64"`（或 `BUILD_ARCHS=all`）。
|
||||
- 使用 `scripts/package-mac-dist.sh` 生成发布产物（zip + DMG + 公证）。使用 `scripts/package-mac-app.sh` 进行本地/开发打包。
|
||||
|
||||
```bash
|
||||
# 从仓库根目录运行；设置发布 ID 以启用 Sparkle 订阅源。
|
||||
# APP_BUILD 必须为纯数字且单调递增，以便 Sparkle 正确比较。
|
||||
BUNDLE_ID=bot.molt.mac \
|
||||
APP_VERSION=2026.1.27-beta.1 \
|
||||
APP_BUILD="$(git rev-list --count HEAD)" \
|
||||
BUILD_CONFIG=release \
|
||||
SIGN_IDENTITY="Developer ID Application: <Developer Name> (<TEAMID>)" \
|
||||
scripts/package-mac-app.sh
|
||||
|
||||
# 打包用于分发的 zip（包含资源分支以支持 Sparkle 增量更新）
|
||||
ditto -c -k --sequesterRsrc --keepParent dist/OpenClaw.app dist/OpenClaw-2026.1.27-beta.1.zip
|
||||
|
||||
# 可选：同时构建适合用户使用的样式化 DMG（拖拽到 /Applications）
|
||||
scripts/create-dmg.sh dist/OpenClaw.app dist/OpenClaw-2026.1.27-beta.1.dmg
|
||||
|
||||
# 推荐：构建 + 公证/装订 zip + DMG
|
||||
# 首先，创建一次钥匙串配置文件：
|
||||
# xcrun notarytool store-credentials "openclaw-notary" \
|
||||
# --apple-id "<apple-id>" --team-id "<team-id>" --password "<app-specific-password>"
|
||||
NOTARIZE=1 NOTARYTOOL_PROFILE=openclaw-notary \
|
||||
BUNDLE_ID=bot.molt.mac \
|
||||
APP_VERSION=2026.1.27-beta.1 \
|
||||
APP_BUILD="$(git rev-list --count HEAD)" \
|
||||
BUILD_CONFIG=release \
|
||||
SIGN_IDENTITY="Developer ID Application: <Developer Name> (<TEAMID>)" \
|
||||
scripts/package-mac-dist.sh
|
||||
|
||||
# 可选：随发布一起提供 dSYM
|
||||
ditto -c -k --keepParent apps/macos/.build/release/OpenClaw.app.dSYM dist/OpenClaw-2026.1.27-beta.1.dSYM.zip
|
||||
```
|
||||
|
||||
## Appcast 条目
|
||||
|
||||
使用发布说明生成器，以便 Sparkle 渲染格式化的 HTML 说明：
|
||||
|
||||
```bash
|
||||
SPARKLE_PRIVATE_KEY_FILE=/path/to/ed25519-private-key scripts/make_appcast.sh dist/OpenClaw-2026.1.27-beta.1.zip https://raw.githubusercontent.com/openclaw/openclaw/main/appcast.xml
|
||||
```
|
||||
|
||||
从 `CHANGELOG.md`（通过 [`scripts/changelog-to-html.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/changelog-to-html.sh)）生成 HTML 发布说明，并将其嵌入 appcast 条目。
|
||||
发布时，将更新后的 `appcast.xml` 与发布资源（zip + dSYM）一起提交。
|
||||
|
||||
## 发布与验证
|
||||
|
||||
- 将 `OpenClaw-2026.1.27-beta.1.zip`（和 `OpenClaw-2026.1.27-beta.1.dSYM.zip`）上传到标签 `v2026.1.27-beta.1` 对应的 GitHub 发布。
|
||||
- 确保原始 appcast URL 与内置的订阅源匹配：`https://raw.githubusercontent.com/openclaw/openclaw/main/appcast.xml`。
|
||||
- 完整性检查：
|
||||
- `curl -I https://raw.githubusercontent.com/openclaw/openclaw/main/appcast.xml` 返回 200。
|
||||
- `curl -I <enclosure url>` 在资源上传后返回 200。
|
||||
- 在之前的公开构建版本上，从 About 选项卡运行"Check for Updates…"，验证 Sparkle 能正常安装新构建。
|
||||
|
||||
完成定义：已签名的应用 + appcast 已发布，从旧版本的更新流程正常工作，且发布资源已附加到 GitHub 发布。
|
||||
90
docs/zh-CN/platforms/mac/remote.md
Normal file
90
docs/zh-CN/platforms/mac/remote.md
Normal file
@@ -0,0 +1,90 @@
|
||||
---
|
||||
read_when:
|
||||
- 设置或调试远程 Mac 控制
|
||||
summary: macOS 应用通过 SSH 远程控制 OpenClaw Gateway 的流程
|
||||
title: 远程控制
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T21:33:20Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: 61b43707250d5515fd0f85f092bdde24598f14904398ff3fca3736bcc48d72f8
|
||||
source_path: platforms/mac/remote.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 远程 OpenClaw（macOS ⇄ 远程主机）
|
||||
|
||||
此流程让 macOS 应用充当运行在另一台主机（桌面/服务器）上的 OpenClaw Gateway 的完整远程控制器。这是应用的 **Remote over SSH**（远程运行）功能。所有功能——健康检查、语音唤醒转发和 Web Chat——都复用 _设置 → 通用_ 中相同的远程 SSH 配置。
|
||||
|
||||
## 模式
|
||||
|
||||
- **本地（此 Mac）**：所有内容在笔记本电脑上运行，无需 SSH。
|
||||
- **Remote over SSH（默认）**：OpenClaw 命令在远程主机上执行。Mac 应用使用 `-o BatchMode` 加上你选择的身份/密钥打开 SSH 连接，并进行本地端口转发。
|
||||
- **Remote direct (ws/wss)**：无 SSH 隧道。Mac 应用直接连接到 Gateway URL（例如通过 Tailscale Serve 或公共 HTTPS 反向代理）。
|
||||
|
||||
## 远程传输方式
|
||||
|
||||
远程模式支持两种传输方式：
|
||||
|
||||
- **SSH 隧道**（默认）：使用 `ssh -N -L ...` 将 Gateway 端口转发到 localhost。由于隧道是回环的，Gateway 会将节点 IP 识别为 `127.0.0.1`。
|
||||
- **Direct (ws/wss)**：直接连接到 Gateway URL。Gateway 会看到真实的客户端 IP。
|
||||
|
||||
## 远程主机的前提条件
|
||||
|
||||
1. 安装 Node + pnpm 并构建/安装 OpenClaw CLI（`pnpm install && pnpm build && pnpm link --global`）。
|
||||
2. 确保 `openclaw` 在非交互式 shell 的 PATH 中（如有需要，创建符号链接到 `/usr/local/bin` 或 `/opt/homebrew/bin`）。
|
||||
3. 开启 SSH 密钥认证。我们建议使用 **Tailscale** IP 以实现局域网外的稳定可达性。
|
||||
|
||||
## macOS 应用设置
|
||||
|
||||
1. 打开 _设置 → 通用_。
|
||||
2. 在 **OpenClaw runs** 下，选择 **Remote over SSH** 并设置：
|
||||
- **传输方式**：**SSH 隧道** 或 **Direct (ws/wss)**。
|
||||
- **SSH 目标**：`user@host`（可选 `:port`）。
|
||||
- 如果 Gateway 在同一局域网中并通过 Bonjour 广播，可从发现列表中选择以自动填充此字段。
|
||||
- **Gateway URL**（仅 Direct 模式）：`wss://gateway.example.ts.net`（或局域网使用 `ws://...`）。
|
||||
- **身份文件**（高级）：密钥路径。
|
||||
- **项目根目录**（高级）：用于命令执行的远程代码仓库路径。
|
||||
- **CLI 路径**（高级）：可选的 `openclaw` 可执行入口/二进制文件路径（广播时自动填充）。
|
||||
3. 点击 **测试远程连接**。成功表示远程 `openclaw status --json` 正常运行。失败通常意味着 PATH/CLI 问题；exit 127 表示远程未找到 CLI。
|
||||
4. 健康检查和 Web Chat 现在会自动通过此 SSH 隧道运行。
|
||||
|
||||
## Web Chat
|
||||
|
||||
- **SSH 隧道**：Web Chat 通过转发的 WebSocket 控制端口（默认 18789）连接到 Gateway。
|
||||
- **Direct (ws/wss)**：Web Chat 直接连接到配置的 Gateway URL。
|
||||
- 不再有单独的 WebChat HTTP 服务器。
|
||||
|
||||
## 权限
|
||||
|
||||
- 远程主机需要与本地相同的 TCC 授权（自动化、辅助功能、屏幕录制、麦克风、语音识别、通知）。在该机器上运行上手引导以一次性授予权限。
|
||||
- 节点通过 `node.list` / `node.describe` 广播其权限状态，以便智能体了解可用功能。
|
||||
|
||||
## 安全注意事项
|
||||
|
||||
- 建议在远程主机上绑定回环地址，并通过 SSH 或 Tailscale 连接。
|
||||
- 如果将 Gateway 绑定到非回环接口，请要求令牌/密码认证。
|
||||
- 参阅 [安全](/gateway/security) 和 [Tailscale](/gateway/tailscale)。
|
||||
|
||||
## WhatsApp 登录流程（远程）
|
||||
|
||||
- 在**远程主机**上运行 `openclaw channels login --verbose`。用手机上的 WhatsApp 扫描二维码。
|
||||
- 如果认证过期，在该主机上重新运行登录。健康检查会显示链接问题。
|
||||
|
||||
## 故障排除
|
||||
|
||||
- **exit 127 / not found**：`openclaw` 不在非登录 shell 的 PATH 中。将其添加到 `/etc/paths`、你的 shell rc 文件中，或创建符号链接到 `/usr/local/bin`/`/opt/homebrew/bin`。
|
||||
- **健康探测失败**：检查 SSH 可达性、PATH，以及 Baileys 是否已登录（`openclaw status --json`）。
|
||||
- **Web Chat 卡住**：确认 Gateway 在远程主机上正在运行，且转发端口与 Gateway WS 端口匹配；界面需要健康的 WS 连接。
|
||||
- **节点 IP 显示 127.0.0.1**：使用 SSH 隧道时这是预期行为。如果你希望 Gateway 看到真实客户端 IP，请将**传输方式**切换为 **Direct (ws/wss)**。
|
||||
- **语音唤醒**：触发短语在远程模式下会自动转发；无需单独的转发器。
|
||||
|
||||
## 通知声音
|
||||
|
||||
通过 `openclaw` 和 `node.invoke` 在脚本中为每个通知选择声音，例如：
|
||||
|
||||
```bash
|
||||
openclaw nodes notify --node <id> --title "Ping" --body "Remote gateway ready" --sound Glass
|
||||
```
|
||||
|
||||
应用中不再有全局"默认声音"开关；调用方按请求选择声音（或不使用声音）。
|
||||
54
docs/zh-CN/platforms/mac/signing.md
Normal file
54
docs/zh-CN/platforms/mac/signing.md
Normal file
@@ -0,0 +1,54 @@
|
||||
---
|
||||
read_when:
|
||||
- 构建或签名 Mac 调试构建
|
||||
summary: 打包脚本生成的 macOS 调试构建的签名步骤
|
||||
title: macOS 签名
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T21:33:15Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: 403b92f9a0ecdb7cb42ec097c684b7a696be3696d6eece747314a4dc90d8797e
|
||||
source_path: platforms/mac/signing.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Mac 签名（调试构建）
|
||||
|
||||
此应用通常从 [`scripts/package-mac-app.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/package-mac-app.sh) 构建，该脚本目前会：
|
||||
|
||||
- 设置稳定的调试 Bundle 标识符：`ai.openclaw.mac.debug`
|
||||
- 使用该 Bundle ID 写入 Info.plist（可通过 `BUNDLE_ID=...` 覆盖）
|
||||
- 调用 [`scripts/codesign-mac-app.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/codesign-mac-app.sh) 对主二进制文件和应用包进行签名，使 macOS 将每次重新构建视为相同的已签名包，并保留 TCC 权限（通知、辅助功能、屏幕录制、麦克风、语音）。要获得稳定的权限，请使用真实签名身份；临时签名是可选的且不稳定（参阅 [macOS 权限](/platforms/mac/permissions)）。
|
||||
- 默认使用 `CODESIGN_TIMESTAMP=auto`；为 Developer ID 签名启用受信任的时间戳。设置 `CODESIGN_TIMESTAMP=off` 可跳过时间戳（离线调试构建）。
|
||||
- 将构建元数据注入 Info.plist：`OpenClawBuildTimestamp`（UTC）和 `OpenClawGitCommit`（短哈希），以便"关于"面板可以显示构建信息、git 信息和调试/发布渠道。
|
||||
- **打包需要 Node 22+**：脚本会运行 TS 构建和 Control UI 构建。
|
||||
- 从环境变量中读取 `SIGN_IDENTITY`。将 `export SIGN_IDENTITY="Apple Development: Your Name (TEAMID)"`（或你的 Developer ID Application 证书）添加到 shell 配置文件中，以始终使用你的证书签名。临时签名需要通过 `ALLOW_ADHOC_SIGNING=1` 或 `SIGN_IDENTITY="-"` 显式启用（不建议用于权限测试）。
|
||||
- 签名后运行 Team ID 审计，如果应用包内的任何 Mach-O 文件由不同的 Team ID 签名则会失败。设置 `SKIP_TEAM_ID_CHECK=1` 可跳过此检查。
|
||||
|
||||
## 用法
|
||||
|
||||
```bash
|
||||
# 从仓库根目录
|
||||
scripts/package-mac-app.sh # 自动选择身份；未找到时报错
|
||||
SIGN_IDENTITY="Developer ID Application: Your Name" scripts/package-mac-app.sh # 真实证书
|
||||
ALLOW_ADHOC_SIGNING=1 scripts/package-mac-app.sh # 临时签名（权限不会持久化）
|
||||
SIGN_IDENTITY="-" scripts/package-mac-app.sh # 显式临时签名（同样的限制）
|
||||
DISABLE_LIBRARY_VALIDATION=1 scripts/package-mac-app.sh # 仅限开发的 Sparkle Team ID 不匹配解决方案
|
||||
```
|
||||
|
||||
### 临时签名注意事项
|
||||
|
||||
使用 `SIGN_IDENTITY="-"`（临时签名）签名时，脚本会自动禁用**强化运行时**（`--options runtime`）。这是为了防止应用在尝试加载不共享相同 Team ID 的嵌入式框架（如 Sparkle）时崩溃。临时签名还会破坏 TCC 权限持久化；参阅 [macOS 权限](/platforms/mac/permissions) 了解恢复步骤。
|
||||
|
||||
## 关于面板的构建元数据
|
||||
|
||||
`package-mac-app.sh` 会在包中标记以下信息：
|
||||
|
||||
- `OpenClawBuildTimestamp`：打包时的 ISO8601 UTC 时间
|
||||
- `OpenClawGitCommit`：短 git 哈希（不可用时为 `unknown`）
|
||||
|
||||
"关于"选项卡读取这些键以显示版本、构建日期、git 提交以及是否为调试构建（通过 `#if DEBUG`）。代码更改后运行打包程序以刷新这些值。
|
||||
|
||||
## 原因
|
||||
|
||||
TCC 权限与 Bundle 标识符*和*代码签名绑定。使用不断变化的 UUID 的未签名调试构建会导致 macOS 在每次重新构建后忘记授权。对二进制文件进行签名（默认临时签名）并保持固定的 Bundle ID/路径（`dist/OpenClaw.app`）可以在构建之间保留授权，与 VibeTunnel 的方案一致。
|
||||
40
docs/zh-CN/platforms/mac/skills.md
Normal file
40
docs/zh-CN/platforms/mac/skills.md
Normal file
@@ -0,0 +1,40 @@
|
||||
---
|
||||
read_when:
|
||||
- 更新 macOS 技能设置 UI
|
||||
- 更改技能门控或安装行为
|
||||
summary: macOS 技能设置 UI 及 Gateway 支持的状态
|
||||
title: 技能
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T21:33:07Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: ecd5286bbe49eed89319686c4f7d6da55ef7b0d3952656ba98ef5e769f3fbf79
|
||||
source_path: platforms/mac/skills.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 技能（macOS）
|
||||
|
||||
macOS 应用通过 Gateway 展示 OpenClaw 技能；不会在本地解析技能。
|
||||
|
||||
## 数据来源
|
||||
|
||||
- `skills.status`（Gateway）返回所有技能及其资格和缺失的依赖项
|
||||
（包括内置技能的白名单限制）。
|
||||
- 依赖项来源于每个 `SKILL.md` 中的 `metadata.openclaw.requires`。
|
||||
|
||||
## 安装操作
|
||||
|
||||
- `metadata.openclaw.install` 定义安装选项（brew/node/go/uv）。
|
||||
- 应用调用 `skills.install` 在 Gateway 主机上运行安装程序。
|
||||
- 当提供多个安装程序时，Gateway 仅展示一个首选安装程序
|
||||
（优先使用 brew，否则使用 `skills.install` 中的 node 管理器，默认为 npm）。
|
||||
|
||||
## 环境变量/API 密钥
|
||||
|
||||
- 应用将密钥存储在 `~/.openclaw/openclaw.json` 的 `skills.entries.<skillKey>` 下。
|
||||
- `skills.update` 可修改 `enabled`、`apiKey` 和 `env`。
|
||||
|
||||
## 远程模式
|
||||
|
||||
- 安装和配置更新在 Gateway 主机上执行（而非本地 Mac）。
|
||||
67
docs/zh-CN/platforms/mac/voice-overlay.md
Normal file
67
docs/zh-CN/platforms/mac/voice-overlay.md
Normal file
@@ -0,0 +1,67 @@
|
||||
---
|
||||
read_when:
|
||||
- 调整语音浮层行为
|
||||
summary: 唤醒词与按键说话重叠时的语音浮层生命周期
|
||||
title: 语音浮层
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T21:33:26Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: 3be1a60aa7940b2368ff62cd49f04b2b8422876030e8ea206b467f66a5a6bd4d
|
||||
source_path: platforms/mac/voice-overlay.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 语音浮层生命周期（macOS）
|
||||
|
||||
受众：macOS 应用贡献者。目标：在唤醒词与按键说话重叠时保持语音浮层行为可预测。
|
||||
|
||||
### 当前意图
|
||||
|
||||
- 如果浮层已因唤醒词显示，此时用户按下热键，热键会话会*接管*现有文本而非重置。浮层在热键按住期间保持显示。用户松开时：如果有去除空白后的文本则发送，否则关闭。
|
||||
- 单独使用唤醒词时仍在静音后自动发送；按键说话在松开时立即发送。
|
||||
|
||||
### 已实现（2025 年 12 月 9 日）
|
||||
|
||||
- 浮层会话现在为每次捕获（唤醒词或按键说话）携带一个令牌。当令牌不匹配时，部分/最终/发送/关闭/音量更新会被丢弃，避免过时回调。
|
||||
- 按键说话会接管任何可见的浮层文本作为前缀（因此在唤醒浮层显示时按下热键会保留文本并追加新语音）。它最多等待 1.5 秒获取最终转录结果，然后回退到当前文本。
|
||||
- 提示音/浮层日志以 `info` 级别输出，分类为 `voicewake.overlay`、`voicewake.ptt` 和 `voicewake.chime`（会话开始、部分、最终、发送、关闭、提示音原因）。
|
||||
|
||||
### 后续步骤
|
||||
|
||||
1. **VoiceSessionCoordinator（actor）**
|
||||
- 同一时间只拥有一个 `VoiceSession`。
|
||||
- API（基于令牌）：`beginWakeCapture`、`beginPushToTalk`、`updatePartial`、`endCapture`、`cancel`、`applyCooldown`。
|
||||
- 丢弃携带过时令牌的回调（防止旧识别器重新打开浮层）。
|
||||
2. **VoiceSession（模型）**
|
||||
- 字段：`token`、`source`（wakeWord|pushToTalk）、已提交/临时文本、提示音标志、计时器（自动发送、空闲）、`overlayMode`（display|editing|sending）、冷却截止时间。
|
||||
3. **浮层绑定**
|
||||
- `VoiceSessionPublisher`（`ObservableObject`）将活跃会话镜像到 SwiftUI。
|
||||
- `VoiceWakeOverlayView` 仅通过 publisher 渲染；绝不直接修改全局单例。
|
||||
- 浮层用户操作（`sendNow`、`dismiss`、`edit`）携带会话令牌回调到 coordinator。
|
||||
4. **统一发送路径**
|
||||
- `endCapture` 时：如果去除空白后文本为空 → 关闭；否则 `performSend(session:)`（播放一次发送提示音、转发、关闭）。
|
||||
- 按键说话：无延迟；唤醒词：可选自动发送延迟。
|
||||
- 按键说话结束后对唤醒运行时施加短暂冷却，防止唤醒词立即重新触发。
|
||||
5. **日志**
|
||||
- Coordinator 在子系统 `bot.molt`、分类 `voicewake.overlay` 和 `voicewake.chime` 下输出 `.info` 级别日志。
|
||||
- 关键事件：`session_started`、`adopted_by_push_to_talk`、`partial`、`finalized`、`send`、`dismiss`、`cancel`、`cooldown`。
|
||||
|
||||
### 调试清单
|
||||
|
||||
- 复现浮层粘滞问题时流式查看日志：
|
||||
|
||||
```bash
|
||||
sudo log stream --predicate 'subsystem == "bot.molt" AND category CONTAINS "voicewake"' --level info --style compact
|
||||
```
|
||||
|
||||
- 验证只有一个活跃会话令牌；过时回调应被 coordinator 丢弃。
|
||||
- 确保按键说话松开时始终使用活跃令牌调用 `endCapture`；如果文本为空，预期 `dismiss` 且不播放提示音或发送。
|
||||
|
||||
### 迁移步骤（建议）
|
||||
|
||||
1. 添加 `VoiceSessionCoordinator`、`VoiceSession` 和 `VoiceSessionPublisher`。
|
||||
2. 重构 `VoiceWakeRuntime`，使其创建/更新/结束会话，而非直接操作 `VoiceWakeOverlayController`。
|
||||
3. 重构 `VoicePushToTalk`，使其接管现有会话并在松开时调用 `endCapture`；施加运行时冷却。
|
||||
4. 将 `VoiceWakeOverlayController` 连接到 publisher；移除来自 runtime/PTT 的直接调用。
|
||||
5. 添加会话接管、冷却和空文本关闭的集成测试。
|
||||
74
docs/zh-CN/platforms/mac/voicewake.md
Normal file
74
docs/zh-CN/platforms/mac/voicewake.md
Normal file
@@ -0,0 +1,74 @@
|
||||
---
|
||||
read_when:
|
||||
- 正在开发语音唤醒或按键通话相关功能
|
||||
summary: Mac 应用中的语音唤醒和按键通话模式及路由详情
|
||||
title: 语音唤醒
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T21:33:32Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: f6440bb89f349ba5c1c9aacffe95e568681beb9899ca736dedfe2f4a366cb5e4
|
||||
source_path: platforms/mac/voicewake.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 语音唤醒与按键通话
|
||||
|
||||
## 模式
|
||||
|
||||
- **唤醒词模式**（默认）：常驻语音识别器等待触发词（`swabbleTriggerWords`）。匹配后开始采集，显示叠加层并展示部分文本，静默后自动发送。
|
||||
- **按键通话（长按右 Option 键）**：长按右 Option 键立即开始采集——无需触发词。长按期间显示叠加层；松开后完成采集并在短暂延迟后转发，以便您调整文本。
|
||||
|
||||
## 运行时行为（唤醒词）
|
||||
|
||||
- 语音识别器位于 `VoiceWakeRuntime` 中。
|
||||
- 仅当唤醒词和下一个词之间存在**有意义的停顿**（约 0.55 秒间隔）时才会触发。叠加层/提示音可以在停顿时启动，甚至在命令开始之前。
|
||||
- 静默窗口：语音持续时为 2.0 秒，仅听到触发词时为 5.0 秒。
|
||||
- 硬停止：120 秒，防止会话失控。
|
||||
- 会话间去抖：350 毫秒。
|
||||
- 叠加层通过 `VoiceWakeOverlayController` 驱动，具有已确认/临时着色。
|
||||
- 发送后，识别器干净重启以监听下一个触发词。
|
||||
|
||||
## 生命周期不变量
|
||||
|
||||
- 如果语音唤醒已启用且权限已授予，唤醒词识别器应保持监听状态（显式按键通话采集期间除外）。
|
||||
- 叠加层可见性（包括通过 X 按钮手动关闭）绝不能阻止识别器恢复。
|
||||
|
||||
## 叠加层卡住故障模式（历史问题）
|
||||
|
||||
此前，如果叠加层卡在可见状态并且您手动关闭它，语音唤醒可能表现为"无响应"，因为运行时的重启尝试会被叠加层可见性阻塞，且不会调度后续重启。
|
||||
|
||||
加固措施：
|
||||
|
||||
- 唤醒运行时重启不再被叠加层可见性阻塞。
|
||||
- 叠加层关闭完成后通过 `VoiceSessionCoordinator` 触发 `VoiceWakeRuntime.refresh(...)`，因此手动点击 X 关闭始终会恢复监听。
|
||||
|
||||
## 按键通话详情
|
||||
|
||||
- 热键检测使用全局 `.flagsChanged` 监视器检测**右 Option 键**（`keyCode 61` + `.option`）。我们仅观察事件（不拦截）。
|
||||
- 采集管道位于 `VoicePushToTalk` 中：立即启动语音识别，将部分结果流式传输到叠加层，松开时调用 `VoiceWakeForwarder`。
|
||||
- 按键通话开始时，我们暂停唤醒词运行时以避免音频输入冲突；松开后自动重启。
|
||||
- 权限：需要麦克风 + 语音识别权限；查看事件需要辅助功能/输入监控授权。
|
||||
- 外接键盘：某些键盘可能无法按预期暴露右 Option 键——如果用户反馈未响应，请提供备用快捷键。
|
||||
|
||||
## 面向用户的设置
|
||||
|
||||
- **语音唤醒**开关：启用唤醒词运行时。
|
||||
- **长按 Cmd+Fn 说话**：启用按键通话监视器。在 macOS < 26 上禁用。
|
||||
- 语言和麦克风选择器、实时电平指示器、触发词表格、测试器（仅本地；不进行转发）。
|
||||
- 麦克风选择器在设备断开时保留上次选择，显示断开提示，并在设备恢复前临时回退到系统默认设备。
|
||||
- **声音**：触发检测和发送时播放提示音；默认使用 macOS "Glass" 系统声音。您可以为每个事件选择任何 `NSSound` 可加载的文件（如 MP3/WAV/AIFF），或选择**无声音**。
|
||||
|
||||
## 转发行为
|
||||
|
||||
- 启用语音唤醒后，转录文本将转发到活跃的 Gateway/智能体（与 Mac 应用其他部分使用的本地/远程模式相同）。
|
||||
- 回复将发送到**最近使用的主要提供商**（WhatsApp/Telegram/Discord/WebChat）。如果发送失败，错误会被记录，且运行仍可通过 WebChat/会话日志查看。
|
||||
|
||||
## 转发载荷
|
||||
|
||||
- `VoiceWakeForwarder.prefixedTranscript(_:)` 在发送前添加机器提示前缀。唤醒词和按键通话路径共用此逻辑。
|
||||
|
||||
## 快速验证
|
||||
|
||||
- 开启按键通话，长按 Cmd+Fn，说话，松开：叠加层应显示部分结果然后发送。
|
||||
- 长按期间，菜单栏耳朵图标应保持放大状态（使用 `triggerVoiceEars(ttl:nil)`）；松开后恢复。
|
||||
43
docs/zh-CN/platforms/mac/webchat.md
Normal file
43
docs/zh-CN/platforms/mac/webchat.md
Normal file
@@ -0,0 +1,43 @@
|
||||
---
|
||||
read_when:
|
||||
- 调试 Mac WebChat 视图或回环端口
|
||||
summary: Mac 应用如何嵌入 Gateway WebChat 以及如何调试
|
||||
title: WebChat
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T21:33:23Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: 04ff448758e530098e2004625f33e42fc3dbe31137cd3beec2d55590e507de08
|
||||
source_path: platforms/mac/webchat.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# WebChat（macOS 应用）
|
||||
|
||||
macOS 菜单栏应用将 WebChat UI 嵌入为原生 SwiftUI 视图。它连接到 Gateway，默认使用所选智能体的**主会话**（通过会话切换器可访问其他会话）。
|
||||
|
||||
- **本地模式**：直接连接到本地 Gateway WebSocket。
|
||||
- **远程模式**：通过 SSH 转发 Gateway 控制端口，并使用该隧道作为数据平面。
|
||||
|
||||
## 启动与调试
|
||||
|
||||
- 手动：Lobster 菜单 → "Open Chat"。
|
||||
- 测试时自动打开：
|
||||
```bash
|
||||
dist/OpenClaw.app/Contents/MacOS/OpenClaw --webchat
|
||||
```
|
||||
- 日志：`./scripts/clawlog.sh`（子系统 `bot.molt`，类别 `WebChatSwiftUI`）。
|
||||
|
||||
## 工作原理
|
||||
|
||||
- 数据平面：Gateway WS 方法 `chat.history`、`chat.send`、`chat.abort`、`chat.inject` 以及事件 `chat`、`agent`、`presence`、`tick`、`health`。
|
||||
- 会话：默认使用主会话（`main`，或作用域为全局时使用 `global`）。UI 可在会话之间切换。
|
||||
- 上手引导使用专用会话，以将首次运行设置与其他内容分开。
|
||||
|
||||
## 安全面
|
||||
|
||||
- 远程模式仅通过 SSH 转发 Gateway WebSocket 控制端口。
|
||||
|
||||
## 已知限制
|
||||
|
||||
- UI 针对聊天会话进行了优化（不是完整的浏览器沙箱）。
|
||||
68
docs/zh-CN/platforms/mac/xpc.md
Normal file
68
docs/zh-CN/platforms/mac/xpc.md
Normal file
@@ -0,0 +1,68 @@
|
||||
---
|
||||
read_when:
|
||||
- 编辑 IPC 协议或菜单栏应用 IPC
|
||||
summary: OpenClaw 应用、gateway 节点传输和 PeekabooBridge 的 macOS IPC 架构
|
||||
title: macOS IPC
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T21:33:31Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: d0211c334a4a59b71afb29dd7b024778172e529fa618985632d3d11d795ced92
|
||||
source_path: platforms/mac/xpc.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# OpenClaw macOS IPC 架构
|
||||
|
||||
**当前模型：** 本地 Unix 套接字将**节点宿主服务**连接到 **macOS 应用**，用于执行审批和 `system.run`。存在一个 `openclaw-mac` 调试 CLI 用于发现/连接检查；智能体操作仍通过 Gateway WebSocket 和 `node.invoke` 传递。UI 自动化使用 PeekabooBridge。
|
||||
|
||||
## 目标
|
||||
|
||||
- 单个 GUI 应用实例负责所有面向 TCC 的工作（通知、屏幕录制、麦克风、语音、AppleScript）。
|
||||
- 精简的自动化接口：Gateway + 节点命令，加上用于 UI 自动化的 PeekabooBridge。
|
||||
- 可预测的权限：始终使用相同的已签名 bundle ID，由 launchd 启动，确保 TCC 授权持久有效。
|
||||
|
||||
## 工作原理
|
||||
|
||||
### Gateway + 节点传输
|
||||
|
||||
- 应用运行 Gateway（本地模式）并作为节点连接到它。
|
||||
- 智能体操作通过 `node.invoke` 执行（例如 `system.run`、`system.notify`、`canvas.*`）。
|
||||
|
||||
### 节点服务 + 应用 IPC
|
||||
|
||||
- 无界面的节点宿主服务通过 WebSocket 连接到 Gateway。
|
||||
- `system.run` 请求通过本地 Unix 套接字转发到 macOS 应用。
|
||||
- 应用在 UI 上下文中执行操作，必要时提示用户确认，并返回输出。
|
||||
|
||||
架构图（SCI）：
|
||||
|
||||
```
|
||||
Agent -> Gateway -> Node Service (WS)
|
||||
| IPC (UDS + token + HMAC + TTL)
|
||||
v
|
||||
Mac App (UI + TCC + system.run)
|
||||
```
|
||||
|
||||
### PeekabooBridge（UI 自动化）
|
||||
|
||||
- UI 自动化使用名为 `bridge.sock` 的独立 UNIX 套接字和 PeekabooBridge JSON 协议。
|
||||
- 宿主优先级顺序（客户端侧）：Peekaboo.app → Claude.app → OpenClaw.app → 本地执行。
|
||||
- 安全性：bridge 宿主要求允许的 TeamID；仅 DEBUG 模式下的同 UID 回退机制受 `PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1`（Peekaboo 约定）保护。
|
||||
- 详见：[PeekabooBridge 用法](/platforms/mac/peekaboo)。
|
||||
|
||||
## 操作流程
|
||||
|
||||
- 重启/重新构建：`SIGN_IDENTITY="Apple Development: <Developer Name> (<TEAMID>)" scripts/restart-mac.sh`
|
||||
- 终止现有实例
|
||||
- Swift 构建 + 打包
|
||||
- 写入/引导/启动 LaunchAgent
|
||||
- 单实例：如果另一个具有相同 bundle ID 的实例正在运行，应用会提前退出。
|
||||
|
||||
## 安全加固说明
|
||||
|
||||
- 优先要求所有特权接口进行 TeamID 匹配。
|
||||
- PeekabooBridge：`PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1`（仅 DEBUG 模式）可允许同 UID 调用方用于本地开发。
|
||||
- 所有通信仅限本地；不暴露网络套接字。
|
||||
- TCC 提示仅来自 GUI 应用 bundle；跨重新构建时保持已签名的 bundle ID 稳定。
|
||||
- IPC 加固：套接字模式 `0600`、令牌、对端 UID 检查、HMAC 质询/响应、短 TTL。
|
||||
288
docs/zh-CN/platforms/macos-vm.md
Normal file
288
docs/zh-CN/platforms/macos-vm.md
Normal file
@@ -0,0 +1,288 @@
|
||||
---
|
||||
read_when:
|
||||
- 你希望将 OpenClaw 与主 macOS 环境隔离运行
|
||||
- 你需要在沙盒中集成 iMessage（BlueBubbles）
|
||||
- 你需要一个可重置、可克隆的 macOS 环境
|
||||
- 你想比较本地与托管 macOS 虚拟机方案
|
||||
summary: 在沙盒化的 macOS 虚拟机（本地或托管）中运行 OpenClaw，适用于需要隔离环境或 iMessage 的场景
|
||||
title: macOS 虚拟机
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T21:33:51Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: 4d1c85a5e4945f9f0796038cd5960edecb71ec4dffb6f9686be50adb75180716
|
||||
source_path: platforms/macos-vm.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 在 macOS 虚拟机上运行 OpenClaw（沙盒化）
|
||||
|
||||
## 推荐默认方案（大多数用户）
|
||||
|
||||
- **小型 Linux VPS**，用于始终在线的 Gateway，成本低廉。参阅 [VPS 托管](/vps)。
|
||||
- **专用硬件**（Mac mini 或 Linux 主机），如果你需要完全控制和**住宅 IP** 以进行浏览器自动化。许多网站会屏蔽数据中心 IP，因此本地浏览通常效果更好。
|
||||
- **混合方案：** 将 Gateway 部署在廉价 VPS 上，需要浏览器/UI 自动化时将你的 Mac 作为**节点**连接。参阅 [节点](/nodes) 和 [Gateway 远程控制](/gateway/remote)。
|
||||
|
||||
当你特别需要 macOS 专有功能（iMessage/BlueBubbles）或希望与日常使用的 Mac 严格隔离时，请使用 macOS 虚拟机。
|
||||
|
||||
## macOS 虚拟机方案
|
||||
|
||||
### 在 Apple Silicon Mac 上运行本地虚拟机（Lume）
|
||||
|
||||
使用 [Lume](https://cua.ai/docs/lume) 在现有的 Apple Silicon Mac 上以沙盒化的 macOS 虚拟机运行 OpenClaw。
|
||||
|
||||
这将为你提供：
|
||||
|
||||
- 隔离的完整 macOS 环境（宿主机保持干净）
|
||||
- 通过 BlueBubbles 支持 iMessage（Linux/Windows 上无法实现）
|
||||
- 通过克隆虚拟机即时重置
|
||||
- 无需额外硬件或云端费用
|
||||
|
||||
### 托管 Mac 提供商（云端）
|
||||
|
||||
如果你需要云端的 macOS，托管 Mac 提供商也可以：
|
||||
|
||||
- [MacStadium](https://www.macstadium.com/)（托管 Mac）
|
||||
- 其他托管 Mac 供应商同样适用；按照其虚拟机 + SSH 文档操作
|
||||
|
||||
获得 macOS 虚拟机的 SSH 访问权限后，继续下方步骤 6。
|
||||
|
||||
---
|
||||
|
||||
## 快速路径（Lume，有经验的用户）
|
||||
|
||||
1. 安装 Lume
|
||||
2. `lume create openclaw --os macos --ipsw latest`
|
||||
3. 完成设置助理，启用远程登录（SSH）
|
||||
4. `lume run openclaw --no-display`
|
||||
5. SSH 登录，安装 OpenClaw，配置渠道
|
||||
6. 完成
|
||||
|
||||
---
|
||||
|
||||
## 准备工作（Lume）
|
||||
|
||||
- Apple Silicon Mac（M1/M2/M3/M4）
|
||||
- 宿主机运行 macOS Sequoia 或更高版本
|
||||
- 每个虚拟机约 60 GB 可用磁盘空间
|
||||
- 约 20 分钟
|
||||
|
||||
---
|
||||
|
||||
## 1) 安装 Lume
|
||||
|
||||
```bash
|
||||
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)"
|
||||
```
|
||||
|
||||
如果 `~/.local/bin` 不在你的 PATH 中：
|
||||
|
||||
```bash
|
||||
echo 'export PATH="$PATH:$HOME/.local/bin"' >> ~/.zshrc && source ~/.zshrc
|
||||
```
|
||||
|
||||
验证：
|
||||
|
||||
```bash
|
||||
lume --version
|
||||
```
|
||||
|
||||
文档：[Lume 安装指南](https://cua.ai/docs/lume/guide/getting-started/installation)
|
||||
|
||||
---
|
||||
|
||||
## 2) 创建 macOS 虚拟机
|
||||
|
||||
```bash
|
||||
lume create openclaw --os macos --ipsw latest
|
||||
```
|
||||
|
||||
这将下载 macOS 并创建虚拟机。VNC 窗口会自动打开。
|
||||
|
||||
注意：下载时间取决于你的网络连接速度。
|
||||
|
||||
---
|
||||
|
||||
## 3) 完成设置助理
|
||||
|
||||
在 VNC 窗口中：
|
||||
|
||||
1. 选择语言和地区
|
||||
2. 跳过 Apple ID（如果以后需要 iMessage 则登录）
|
||||
3. 创建用户账户（记住用户名和密码）
|
||||
4. 跳过所有可选功能
|
||||
|
||||
设置完成后，启用 SSH：
|
||||
|
||||
1. 打开系统设置 → 通用 → 共享
|
||||
2. 启用"远程登录"
|
||||
|
||||
---
|
||||
|
||||
## 4) 获取虚拟机的 IP 地址
|
||||
|
||||
```bash
|
||||
lume get openclaw
|
||||
```
|
||||
|
||||
查找 IP 地址（通常为 `192.168.64.x`）。
|
||||
|
||||
---
|
||||
|
||||
## 5) SSH 登录虚拟机
|
||||
|
||||
```bash
|
||||
ssh youruser@192.168.64.X
|
||||
```
|
||||
|
||||
将 `youruser` 替换为你创建的账户，IP 替换为你的虚拟机 IP。
|
||||
|
||||
---
|
||||
|
||||
## 6) 安装 OpenClaw
|
||||
|
||||
在虚拟机内：
|
||||
|
||||
```bash
|
||||
npm install -g openclaw@latest
|
||||
openclaw onboard --install-daemon
|
||||
```
|
||||
|
||||
按照上手引导提示设置你的模型提供商（Anthropic、OpenAI 等）。
|
||||
|
||||
---
|
||||
|
||||
## 7) 配置渠道
|
||||
|
||||
编辑配置文件：
|
||||
|
||||
```bash
|
||||
nano ~/.openclaw/openclaw.json
|
||||
```
|
||||
|
||||
添加你的渠道：
|
||||
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"whatsapp": {
|
||||
"dmPolicy": "allowlist",
|
||||
"allowFrom": ["+15551234567"]
|
||||
},
|
||||
"telegram": {
|
||||
"botToken": "YOUR_BOT_TOKEN"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
然后登录 WhatsApp（扫描二维码）：
|
||||
|
||||
```bash
|
||||
openclaw channels login
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8) 无界面运行虚拟机
|
||||
|
||||
停止虚拟机并以无显示模式重启：
|
||||
|
||||
```bash
|
||||
lume stop openclaw
|
||||
lume run openclaw --no-display
|
||||
```
|
||||
|
||||
虚拟机将在后台运行。OpenClaw 的守护进程会保持 Gateway 运行。
|
||||
|
||||
检查状态：
|
||||
|
||||
```bash
|
||||
ssh youruser@192.168.64.X "openclaw status"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 附加功能：iMessage 集成
|
||||
|
||||
这是在 macOS 上运行的杀手级功能。使用 [BlueBubbles](https://bluebubbles.app) 将 iMessage 添加到 OpenClaw。
|
||||
|
||||
在虚拟机内：
|
||||
|
||||
1. 从 bluebubbles.app 下载 BlueBubbles
|
||||
2. 使用你的 Apple ID 登录
|
||||
3. 启用 Web API 并设置密码
|
||||
4. 将 BlueBubbles webhook 指向你的 Gateway（示例：`https://your-gateway-host:3000/bluebubbles-webhook?password=<password>`）
|
||||
|
||||
添加到你的 OpenClaw 配置：
|
||||
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"bluebubbles": {
|
||||
"serverUrl": "http://localhost:1234",
|
||||
"password": "your-api-password",
|
||||
"webhookPath": "/bluebubbles-webhook"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
重启 Gateway。现在你的智能体可以收发 iMessage 了。
|
||||
|
||||
完整设置详情：[BlueBubbles 渠道](/channels/bluebubbles)
|
||||
|
||||
---
|
||||
|
||||
## 保存黄金镜像
|
||||
|
||||
在进一步自定义之前，快照保存你的干净状态：
|
||||
|
||||
```bash
|
||||
lume stop openclaw
|
||||
lume clone openclaw openclaw-golden
|
||||
```
|
||||
|
||||
随时重置：
|
||||
|
||||
```bash
|
||||
lume stop openclaw && lume delete openclaw
|
||||
lume clone openclaw-golden openclaw
|
||||
lume run openclaw --no-display
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 全天候运行
|
||||
|
||||
通过以下方式保持虚拟机运行：
|
||||
|
||||
- 保持 Mac 接通电源
|
||||
- 在系统设置 → 节能中禁用睡眠
|
||||
- 如有需要使用 `caffeinate`
|
||||
|
||||
如需真正的始终在线，请考虑专用 Mac mini 或小型 VPS。参阅 [VPS 托管](/vps)。
|
||||
|
||||
---
|
||||
|
||||
## 故障排除
|
||||
|
||||
| 问题 | 解决方案 |
|
||||
| ----------------------- | --------------------------------------------------------------- |
|
||||
| 无法 SSH 登录虚拟机 | 检查虚拟机系统设置中是否已启用"远程登录" |
|
||||
| 虚拟机 IP 未显示 | 等待虚拟机完全启动，再次运行 `lume get openclaw` |
|
||||
| Lume 命令未找到 | 将 `~/.local/bin` 添加到你的 PATH |
|
||||
| WhatsApp 二维码无法扫描 | 确保运行 `openclaw channels login` 时登录的是虚拟机（非宿主机） |
|
||||
|
||||
---
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [VPS 托管](/vps)
|
||||
- [节点](/nodes)
|
||||
- [Gateway 远程控制](/gateway/remote)
|
||||
- [BlueBubbles 渠道](/channels/bluebubbles)
|
||||
- [Lume 快速入门](https://cua.ai/docs/lume/guide/getting-started/quickstart)
|
||||
- [Lume CLI 参考](https://cua.ai/docs/lume/reference/cli-reference)
|
||||
- [无人值守虚拟机设置](https://cua.ai/docs/lume/guide/fundamentals/unattended-setup)（高级）
|
||||
- [Docker 沙盒化](/install/docker)（替代隔离方案）
|
||||
194
docs/zh-CN/platforms/macos.md
Normal file
194
docs/zh-CN/platforms/macos.md
Normal file
@@ -0,0 +1,194 @@
|
||||
---
|
||||
read_when:
|
||||
- 实现 macOS 应用功能
|
||||
- 更改 macOS 上的 Gateway 生命周期或节点桥接
|
||||
summary: OpenClaw macOS 伴侣应用（菜单栏 + Gateway 代理）
|
||||
title: macOS 应用
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T21:33:53Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: a5b1c02e5905e4cbc6c0688149cdb50a5bf7653e641947143e169ad948d1f057
|
||||
source_path: platforms/macos.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# OpenClaw macOS 伴侣应用（菜单栏 + Gateway 代理）
|
||||
|
||||
macOS 应用是 OpenClaw 的**菜单栏伴侣**。它拥有权限，在本地管理/连接 Gateway（launchd 或手动），并将 macOS 能力作为节点暴露给智能体。
|
||||
|
||||
## 功能说明
|
||||
|
||||
- 在菜单栏显示原生通知和状态。
|
||||
- 拥有 TCC 提示（通知、辅助功能、屏幕录制、麦克风、语音识别、自动化/AppleScript）。
|
||||
- 运行或连接到 Gateway（本地或远程）。
|
||||
- 暴露 macOS 专有工具（画布、摄像头、屏幕录制、`system.run`）。
|
||||
- 在**远程**模式下启动本地节点宿主服务（launchd），在**本地**模式下停止它。
|
||||
- 可选托管 **PeekabooBridge** 用于 UI 自动化。
|
||||
- 根据请求通过 npm/pnpm 安装全局 CLI（`openclaw`）（不建议将 bun 用于 Gateway 运行时）。
|
||||
|
||||
## 本地模式与远程模式
|
||||
|
||||
- **本地**（默认）：如果存在正在运行的本地 Gateway，应用会连接到它；否则通过 `openclaw gateway install` 启用 launchd 服务。
|
||||
- **远程**：应用通过 SSH/Tailscale 连接到 Gateway，不会启动本地进程。
|
||||
应用会启动本地**节点宿主服务**，以便远程 Gateway 可以访问这台 Mac。
|
||||
应用不会将 Gateway 作为子进程启动。
|
||||
|
||||
## Launchd 控制
|
||||
|
||||
应用管理一个标签为 `bot.molt.gateway` 的用户级 LaunchAgent（使用 `--profile`/`OPENCLAW_PROFILE` 时为 `bot.molt.<profile>`；旧版 `com.openclaw.*` 仍会被卸载）。
|
||||
|
||||
```bash
|
||||
launchctl kickstart -k gui/$UID/bot.molt.gateway
|
||||
launchctl bootout gui/$UID/bot.molt.gateway
|
||||
```
|
||||
|
||||
运行命名配置文件时，请将标签替换为 `bot.molt.<profile>`。
|
||||
|
||||
如果 LaunchAgent 未安装，可从应用中启用或运行 `openclaw gateway install`。
|
||||
|
||||
## 节点能力（Mac）
|
||||
|
||||
macOS 应用将自身呈现为一个节点。常用命令：
|
||||
|
||||
- 画布：`canvas.present`、`canvas.navigate`、`canvas.eval`、`canvas.snapshot`、`canvas.a2ui.*`
|
||||
- 摄像头：`camera.snap`、`camera.clip`
|
||||
- 屏幕：`screen.record`
|
||||
- 系统：`system.run`、`system.notify`
|
||||
|
||||
节点上报 `permissions` 映射表，以便智能体判断哪些操作被允许。
|
||||
|
||||
节点服务 + 应用 IPC：
|
||||
|
||||
- 当无头节点宿主服务运行时（远程模式），它通过 WS 作为节点连接到 Gateway。
|
||||
- `system.run` 在 macOS 应用（UI/TCC 上下文）中通过本地 Unix 套接字执行；提示和输出保留在应用内。
|
||||
|
||||
示意图（SCI）：
|
||||
|
||||
```
|
||||
Gateway -> Node Service (WS)
|
||||
| IPC (UDS + token + HMAC + TTL)
|
||||
v
|
||||
Mac App (UI + TCC + system.run)
|
||||
```
|
||||
|
||||
## 执行审批（system.run）
|
||||
|
||||
`system.run` 由 macOS 应用中的**执行审批**控制（设置 → 执行审批）。
|
||||
安全策略 + 询问方式 + 允许列表存储在 Mac 本地：
|
||||
|
||||
```
|
||||
~/.openclaw/exec-approvals.json
|
||||
```
|
||||
|
||||
示例：
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 1,
|
||||
"defaults": {
|
||||
"security": "deny",
|
||||
"ask": "on-miss"
|
||||
},
|
||||
"agents": {
|
||||
"main": {
|
||||
"security": "allowlist",
|
||||
"ask": "on-miss",
|
||||
"allowlist": [{ "pattern": "/opt/homebrew/bin/rg" }]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
注意事项：
|
||||
|
||||
- `allowlist` 条目是解析后二进制路径的 glob 模式。
|
||||
- 在提示中选择"始终允许"会将该命令添加到允许列表中。
|
||||
- `system.run` 环境变量覆盖会先过滤（移除 `PATH`、`DYLD_*`、`LD_*`、`NODE_OPTIONS`、`PYTHON*`、`PERL*`、`RUBYOPT`），然后与应用的环境变量合并。
|
||||
|
||||
## 深度链接
|
||||
|
||||
应用注册 `openclaw://` URL 方案用于本地操作。
|
||||
|
||||
### `openclaw://agent`
|
||||
|
||||
触发 Gateway `agent` 请求。
|
||||
|
||||
```bash
|
||||
open 'openclaw://agent?message=Hello%20from%20deep%20link'
|
||||
```
|
||||
|
||||
查询参数：
|
||||
|
||||
- `message`（必填）
|
||||
- `sessionKey`（可选）
|
||||
- `thinking`（可选）
|
||||
- `deliver` / `to` / `channel`（可选）
|
||||
- `timeoutSeconds`（可选）
|
||||
- `key`（可选，无人值守模式密钥）
|
||||
|
||||
安全性：
|
||||
|
||||
- 不带 `key` 时，应用会提示确认。
|
||||
- 带有有效 `key` 时，运行为无人值守模式（用于个人自动化）。
|
||||
|
||||
## 上手引导流程（典型）
|
||||
|
||||
1. 安装并启动 **OpenClaw.app**。
|
||||
2. 完成权限清单（TCC 提示）。
|
||||
3. 确保**本地**模式已激活且 Gateway 正在运行。
|
||||
4. 如需终端访问，安装 CLI。
|
||||
|
||||
## 构建与开发工作流（原生）
|
||||
|
||||
- `cd apps/macos && swift build`
|
||||
- `swift run OpenClaw`（或 Xcode）
|
||||
- 打包应用：`scripts/package-mac-app.sh`
|
||||
|
||||
## 调试 Gateway 连接（macOS CLI）
|
||||
|
||||
使用调试 CLI 来执行与 macOS 应用相同的 Gateway WebSocket 握手和发现逻辑，无需启动应用。
|
||||
|
||||
```bash
|
||||
cd apps/macos
|
||||
swift run openclaw-mac connect --json
|
||||
swift run openclaw-mac discover --timeout 3000 --json
|
||||
```
|
||||
|
||||
连接选项：
|
||||
|
||||
- `--url <ws://host:port>`：覆盖配置
|
||||
- `--mode <local|remote>`：从配置中解析（默认：配置值或 local）
|
||||
- `--probe`：强制执行新的健康探测
|
||||
- `--timeout <ms>`：请求超时（默认：`15000`）
|
||||
- `--json`：结构化输出，便于对比
|
||||
|
||||
发现选项：
|
||||
|
||||
- `--include-local`：包含会被过滤为"本地"的 Gateway
|
||||
- `--timeout <ms>`：总发现窗口时间（默认：`2000`）
|
||||
- `--json`：结构化输出，便于对比
|
||||
|
||||
提示：与 `openclaw gateway discover --json` 对比，查看 macOS 应用的发现管道（NWBrowser + tailnet DNS-SD 回退）是否与 Node CLI 基于 `dns-sd` 的发现有差异。
|
||||
|
||||
## 远程连接机制（SSH 隧道）
|
||||
|
||||
当 macOS 应用在**远程**模式下运行时，它会打开 SSH 隧道，使本地 UI 组件可以像访问 localhost 一样与远程 Gateway 通信。
|
||||
|
||||
### 控制隧道（Gateway WebSocket 端口）
|
||||
|
||||
- **用途：** 健康检查、状态、Web Chat、配置及其他控制平面调用。
|
||||
- **本地端口：** Gateway 端口（默认 `18789`），始终稳定。
|
||||
- **远程端口：** 远程主机上的相同 Gateway 端口。
|
||||
- **行为：** 不使用随机本地端口；应用复用现有的健康隧道，或在需要时重启。
|
||||
- **SSH 形式：** `ssh -N -L <local>:127.0.0.1:<remote>`，带 BatchMode + ExitOnForwardFailure + keepalive 选项。
|
||||
- **IP 上报：** SSH 隧道使用回环地址，因此 Gateway 看到的节点 IP 为 `127.0.0.1`。如果需要显示真实客户端 IP，请使用 **Direct (ws/wss)** 传输方式（参阅 [macOS 远程访问](/platforms/mac/remote)）。
|
||||
|
||||
有关设置步骤，请参阅 [macOS 远程访问](/platforms/mac/remote)。有关协议详情，请参阅 [Gateway 协议](/gateway/protocol)。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [Gateway 运行手册](/gateway)
|
||||
- [Gateway（macOS）](/platforms/mac/bundled-gateway)
|
||||
- [macOS 权限](/platforms/mac/permissions)
|
||||
- [画布](/platforms/mac/canvas)
|
||||
310
docs/zh-CN/platforms/oracle.md
Normal file
310
docs/zh-CN/platforms/oracle.md
Normal file
@@ -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（回环绑定 + 令牌认证）并启用 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 绑定到回环地址后，你将获得强大的纵深防御：公共流量在网络边缘被阻止，管理访问通过 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 的替代方案
|
||||
365
docs/zh-CN/platforms/raspberry-pi.md
Normal file
365
docs/zh-CN/platforms/raspberry-pi.md
Normal file
@@ -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` |
|
||||
|
||||
如果某个技能运行失败，请检查其二进制文件是否有 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 二进制问题
|
||||
|
||||
如果某个技能报错 "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 配对
|
||||
156
docs/zh-CN/platforms/windows.md
Normal file
156
docs/zh-CN/platforms/windows.md
Normal file
@@ -0,0 +1,156 @@
|
||||
---
|
||||
read_when:
|
||||
- 在 Windows 上安装 OpenClaw
|
||||
- 了解 Windows 伴侣应用的状态
|
||||
summary: Windows (WSL2) 支持 + 伴侣应用状态
|
||||
title: Windows (WSL2)
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T21:34:13Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: c93d2263b4e5b60cb6fbe9adcb1a0ca95b70cd6feb6e63cfc4459cb18b229da0
|
||||
source_path: platforms/windows.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Windows (WSL2)
|
||||
|
||||
推荐**通过 WSL2** 在 Windows 上使用 OpenClaw（建议使用 Ubuntu）。CLI + Gateway 在 Linux 内运行，这样可以保持运行时一致性，并使工具链兼容性更好（Node/Bun/pnpm、Linux 二进制文件、技能）。原生 Windows 可能会更麻烦。WSL2 为你提供完整的 Linux 体验——一条命令即可安装：`wsl --install`。
|
||||
|
||||
原生 Windows 伴侣应用已在计划中。
|
||||
|
||||
## 安装（WSL2）
|
||||
|
||||
- [快速开始](/start/getting-started)（在 WSL 内使用）
|
||||
- [安装与更新](/install/updating)
|
||||
- 官方 WSL2 指南（Microsoft）：https://learn.microsoft.com/windows/wsl/install
|
||||
|
||||
## Gateway
|
||||
|
||||
- [Gateway 运行手册](/gateway)
|
||||
- [配置](/gateway/configuration)
|
||||
|
||||
## Gateway 服务安装（CLI）
|
||||
|
||||
在 WSL2 内：
|
||||
|
||||
```
|
||||
openclaw onboard --install-daemon
|
||||
```
|
||||
|
||||
或：
|
||||
|
||||
```
|
||||
openclaw gateway install
|
||||
```
|
||||
|
||||
或：
|
||||
|
||||
```
|
||||
openclaw configure
|
||||
```
|
||||
|
||||
出现提示时选择 **Gateway 服务**。
|
||||
|
||||
修复/迁移：
|
||||
|
||||
```
|
||||
openclaw doctor
|
||||
```
|
||||
|
||||
## 进阶：通过局域网暴露 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`）；使用 `openclaw status --all` 来确认。
|
||||
- 使用 `listenaddress=0.0.0.0` 进行局域网访问；`127.0.0.1` 仅限本地访问。
|
||||
- 如果你希望自动执行，可以注册一个计划任务，在登录时运行刷新步骤。
|
||||
|
||||
## 分步 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) 安装 OpenClaw（在 WSL 内）
|
||||
|
||||
在 WSL 内按照 Linux 快速开始流程操作：
|
||||
|
||||
```bash
|
||||
git clone https://github.com/openclaw/openclaw.git
|
||||
cd openclaw
|
||||
pnpm install
|
||||
pnpm ui:build # 首次运行时自动安装 UI 依赖
|
||||
pnpm build
|
||||
openclaw onboard
|
||||
```
|
||||
|
||||
完整指南：[快速开始](/start/getting-started)
|
||||
|
||||
## Windows 伴侣应用
|
||||
|
||||
我们目前还没有 Windows 伴侣应用。如果你希望推动此功能的实现，欢迎贡献代码。
|
||||
Reference in New Issue
Block a user