first commit
This commit is contained in:
215
content/install/ansible.md
Normal file
215
content/install/ansible.md
Normal file
@@ -0,0 +1,215 @@
|
||||
---
|
||||
read_when:
|
||||
- 你想要带安全加固的自动化服务器部署
|
||||
- 你需要带 VPN 访问的防火墙隔离设置
|
||||
- 你正在部署到远程 Debian/Ubuntu 服务器
|
||||
summary: 使用 Ansible、Tailscale VPN 和防火墙隔离进行自动化、加固的 OpenClaw 安装
|
||||
title: Ansible
|
||||
x-i18n:
|
||||
generated_at: "2026-02-03T07:49:29Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: 896807f344d923f09039f377c13b4bf4a824aa94eec35159fc169596a3493b29
|
||||
source_path: install/ansible.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Ansible 安装
|
||||
|
||||
将 OpenClaw 部署到生产服务器的推荐方式是通过 **[openclaw-ansible](https://github.com/openclaw/openclaw-ansible)** — 一个安全优先架构的自动化安装程序。
|
||||
|
||||
## 快速开始
|
||||
|
||||
一条命令安装：
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/openclaw/openclaw-ansible/main/install.sh | bash
|
||||
```
|
||||
|
||||
> **📦 完整指南：[github.com/openclaw/openclaw-ansible](https://github.com/openclaw/openclaw-ansible)**
|
||||
>
|
||||
> openclaw-ansible 仓库是 Ansible 部署的权威来源。本页是快速概述。
|
||||
|
||||
## 你将获得
|
||||
|
||||
- 🔒 **防火墙优先安全**：UFW + Docker 隔离（仅 SSH + Tailscale 可访问）
|
||||
- 🔐 **Tailscale VPN**：安全远程访问，无需公开暴露服务
|
||||
- 🐳 **Docker**：隔离的沙箱容器，仅绑定 localhost
|
||||
- 🛡️ **纵深防御**：4 层安全架构
|
||||
- 🚀 **一条命令设置**：几分钟内完成部署
|
||||
- 🔧 **Systemd 集成**：带加固的开机自启动
|
||||
|
||||
## 要求
|
||||
|
||||
- **操作系统**：Debian 11+ 或 Ubuntu 20.04+
|
||||
- **访问权限**：Root 或 sudo 权限
|
||||
- **网络**：用于包安装的互联网连接
|
||||
- **Ansible**：2.14+（由快速启动脚本自动安装）
|
||||
|
||||
## 安装内容
|
||||
|
||||
Ansible playbook 安装并配置：
|
||||
|
||||
1. **Tailscale**（用于安全远程访问的 mesh VPN）
|
||||
2. **UFW 防火墙**（仅允许 SSH + Tailscale 端口）
|
||||
3. **Docker CE + Compose V2**（用于智能体沙箱）
|
||||
4. **Node.js 22.x + pnpm**（运行时依赖）
|
||||
5. **OpenClaw**（基于主机，非容器化）
|
||||
6. **Systemd 服务**（带安全加固的自动启动）
|
||||
|
||||
注意：Gateway 网关**直接在主机上运行**（不在 Docker 中），但智能体沙箱使用 Docker 进行隔离。详情参见[沙箱隔离](/gateway/sandboxing)。
|
||||
|
||||
## 安装后设置
|
||||
|
||||
安装完成后，切换到 openclaw 用户：
|
||||
|
||||
```bash
|
||||
sudo -i -u openclaw
|
||||
```
|
||||
|
||||
安装后脚本将引导你完成：
|
||||
|
||||
1. **新手引导向导**：配置 OpenClaw 设置
|
||||
2. **提供商登录**：连接 WhatsApp/Telegram/Discord/Signal
|
||||
3. **Gateway 网关测试**：验证安装
|
||||
4. **Tailscale 设置**：连接到你的 VPN mesh
|
||||
|
||||
### 常用命令
|
||||
|
||||
```bash
|
||||
# 检查服务状态
|
||||
sudo systemctl status openclaw
|
||||
|
||||
# 查看实时日志
|
||||
sudo journalctl -u openclaw -f
|
||||
|
||||
# 重启 Gateway 网关
|
||||
sudo systemctl restart openclaw
|
||||
|
||||
# 提供商登录（以 openclaw 用户运行）
|
||||
sudo -i -u openclaw
|
||||
openclaw channels login
|
||||
```
|
||||
|
||||
## 安全架构
|
||||
|
||||
### 4 层防御
|
||||
|
||||
1. **防火墙（UFW）**：仅公开暴露 SSH（22）+ Tailscale（41641/udp）
|
||||
2. **VPN（Tailscale）**：Gateway 网关仅通过 VPN mesh 可访问
|
||||
3. **Docker 隔离**：DOCKER-USER iptables 链防止外部端口暴露
|
||||
4. **Systemd 加固**：NoNewPrivileges、PrivateTmp、非特权用户
|
||||
|
||||
### 验证
|
||||
|
||||
测试外部攻击面：
|
||||
|
||||
```bash
|
||||
nmap -p- YOUR_SERVER_IP
|
||||
```
|
||||
|
||||
应该显示**仅端口 22**（SSH）开放。所有其他服务（Gateway 网关、Docker）都被锁定。
|
||||
|
||||
### Docker 可用性
|
||||
|
||||
Docker 用于**智能体沙箱**（隔离的工具执行），而不是用于运行 Gateway 网关本身。Gateway 网关仅绑定到 localhost，通过 Tailscale VPN 访问。
|
||||
|
||||
沙箱配置参见[多智能体沙箱与工具](/tools/multi-agent-sandbox-tools)。
|
||||
|
||||
## 手动安装
|
||||
|
||||
如果你更喜欢手动控制而非自动化：
|
||||
|
||||
```bash
|
||||
# 1. 安装先决条件
|
||||
sudo apt update && sudo apt install -y ansible git
|
||||
|
||||
# 2. 克隆仓库
|
||||
git clone https://github.com/openclaw/openclaw-ansible.git
|
||||
cd openclaw-ansible
|
||||
|
||||
# 3. 安装 Ansible collections
|
||||
ansible-galaxy collection install -r requirements.yml
|
||||
|
||||
# 4. 运行 playbook
|
||||
./run-playbook.sh
|
||||
|
||||
# 或直接运行（然后手动执行 /tmp/openclaw-setup.sh）
|
||||
# ansible-playbook playbook.yml --ask-become-pass
|
||||
```
|
||||
|
||||
## 更新 OpenClaw
|
||||
|
||||
Ansible 安装程序设置 OpenClaw 为手动更新。标准更新流程参见[更新](/install/updating)。
|
||||
|
||||
要重新运行 Ansible playbook（例如，用于配置更改）：
|
||||
|
||||
```bash
|
||||
cd openclaw-ansible
|
||||
./run-playbook.sh
|
||||
```
|
||||
|
||||
注意：这是幂等的，可以安全地多次运行。
|
||||
|
||||
## 故障排除
|
||||
|
||||
### 防火墙阻止了我的连接
|
||||
|
||||
如果你被锁定：
|
||||
|
||||
- 确保你可以先通过 Tailscale VPN 访问
|
||||
- SSH 访问（端口 22）始终允许
|
||||
- Gateway 网关**仅**通过 Tailscale 访问，这是设计如此
|
||||
|
||||
### 服务无法启动
|
||||
|
||||
```bash
|
||||
# 检查日志
|
||||
sudo journalctl -u openclaw -n 100
|
||||
|
||||
# 验证权限
|
||||
sudo ls -la /opt/openclaw
|
||||
|
||||
# 测试手动启动
|
||||
sudo -i -u openclaw
|
||||
cd ~/openclaw
|
||||
pnpm start
|
||||
```
|
||||
|
||||
### Docker 沙箱问题
|
||||
|
||||
```bash
|
||||
# 验证 Docker 正在运行
|
||||
sudo systemctl status docker
|
||||
|
||||
# 检查沙箱镜像
|
||||
sudo docker images | grep openclaw-sandbox
|
||||
|
||||
# 如果缺失则构建沙箱镜像
|
||||
cd /opt/openclaw/openclaw
|
||||
sudo -u openclaw ./scripts/sandbox-setup.sh
|
||||
```
|
||||
|
||||
### 提供商登录失败
|
||||
|
||||
确保你以 `openclaw` 用户运行：
|
||||
|
||||
```bash
|
||||
sudo -i -u openclaw
|
||||
openclaw channels login
|
||||
```
|
||||
|
||||
## 高级配置
|
||||
|
||||
详细的安全架构和故障排除：
|
||||
|
||||
- [安全架构](https://github.com/openclaw/openclaw-ansible/blob/main/docs/security.md)
|
||||
- [技术详情](https://github.com/openclaw/openclaw-ansible/blob/main/docs/architecture.md)
|
||||
- [故障排除指南](https://github.com/openclaw/openclaw-ansible/blob/main/docs/troubleshooting.md)
|
||||
|
||||
## 相关内容
|
||||
|
||||
- [openclaw-ansible](https://github.com/openclaw/openclaw-ansible) — 完整部署指南
|
||||
- [Docker](/install/docker) — 容器化 Gateway 网关设置
|
||||
- [沙箱隔离](/gateway/sandboxing) — 智能体沙箱配置
|
||||
- [多智能体沙箱与工具](/tools/multi-agent-sandbox-tools) — 每个智能体的隔离
|
||||
65
content/install/bun.md
Normal file
65
content/install/bun.md
Normal file
@@ -0,0 +1,65 @@
|
||||
---
|
||||
read_when:
|
||||
- 你想要最快的本地开发循环（bun + watch）
|
||||
- 你遇到 Bun 安装/补丁/生命周期脚本问题
|
||||
summary: Bun 工作流（实验性）：安装及与 pnpm 相比的注意事项
|
||||
title: Bun（实验性）
|
||||
x-i18n:
|
||||
generated_at: "2026-02-03T07:49:24Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: eb3f4c222b6bae49938d8bf53a0818fe5f5e0c0c3c1adb3e0a832ce8f785e1e3
|
||||
source_path: install/bun.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Bun（实验性）
|
||||
|
||||
目标：使用 **Bun** 运行此仓库（可选，不推荐用于 WhatsApp/Telegram），同时不偏离 pnpm 工作流。
|
||||
|
||||
⚠️ **不推荐用于 Gateway 网关运行时**（WhatsApp/Telegram 存在 bug）。生产环境请使用 Node。
|
||||
|
||||
## 状态
|
||||
|
||||
- Bun 是一个可选的本地运行时，用于直接运行 TypeScript（`bun run …`、`bun --watch …`）。
|
||||
- `pnpm` 是构建的默认工具，仍然完全支持（并被一些文档工具使用）。
|
||||
- Bun 无法使用 `pnpm-lock.yaml` 并会忽略它。
|
||||
|
||||
## 安装
|
||||
|
||||
默认：
|
||||
|
||||
```sh
|
||||
bun install
|
||||
```
|
||||
|
||||
注意：`bun.lock`/`bun.lockb` 被 gitignore，所以无论哪种方式都不会有仓库变动。如果你想*不写入锁文件*：
|
||||
|
||||
```sh
|
||||
bun install --no-save
|
||||
```
|
||||
|
||||
## 构建/测试（Bun）
|
||||
|
||||
```sh
|
||||
bun run build
|
||||
bun run vitest run
|
||||
```
|
||||
|
||||
## Bun 生命周期脚本（默认被阻止）
|
||||
|
||||
除非明确信任（`bun pm untrusted` / `bun pm trust`），Bun 可能会阻止依赖的生命周期脚本。
|
||||
对于此仓库，通常被阻止的脚本不是必需的：
|
||||
|
||||
- `@whiskeysockets/baileys` `preinstall`：检查 Node 主版本 >= 20（我们运行 Node 22+）。
|
||||
- `protobufjs` `postinstall`：发出关于不兼容版本方案的警告（无构建产物）。
|
||||
|
||||
如果你遇到真正需要这些脚本的运行时问题，请明确信任它们：
|
||||
|
||||
```sh
|
||||
bun pm trust @whiskeysockets/baileys protobufjs
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
|
||||
- 一些脚本仍然硬编码 pnpm（例如 `docs:build`、`ui:*`、`protocol:check`）。目前请通过 pnpm 运行这些脚本。
|
||||
81
content/install/development-channels.md
Normal file
81
content/install/development-channels.md
Normal file
@@ -0,0 +1,81 @@
|
||||
---
|
||||
read_when:
|
||||
- 你想在 stable/beta/dev 之间切换
|
||||
- 你正在标记或发布预发布版本
|
||||
summary: stable、beta 和 dev 渠道：语义、切换和标签
|
||||
title: 开发渠道
|
||||
x-i18n:
|
||||
generated_at: "2026-02-03T10:07:21Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: 2b01219b7e705044ce39838a0da7c7fa65c719809ab2f8a51e14529064af81bf
|
||||
source_path: install/development-channels.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 开发渠道
|
||||
|
||||
最后更新：2026-01-21
|
||||
|
||||
OpenClaw 提供三个更新渠道：
|
||||
|
||||
- **stable**：npm dist-tag `latest`。
|
||||
- **beta**：npm dist-tag `beta`（测试中的构建）。
|
||||
- **dev**：`main` 的移动头（git）。npm dist-tag：`dev`（发布时）。
|
||||
|
||||
我们将构建发布到 **beta**，进行测试，然后**将经过验证的构建提升到 `latest`**，
|
||||
版本号不变——dist-tag 是 npm 安装的数据源。
|
||||
|
||||
## 切换渠道
|
||||
|
||||
Git checkout：
|
||||
|
||||
```bash
|
||||
openclaw update --channel stable
|
||||
openclaw update --channel beta
|
||||
openclaw update --channel dev
|
||||
```
|
||||
|
||||
- `stable`/`beta` 检出最新匹配的标签（通常是同一个标签）。
|
||||
- `dev` 切换到 `main` 并在上游基础上 rebase。
|
||||
|
||||
npm/pnpm 全局安装：
|
||||
|
||||
```bash
|
||||
openclaw update --channel stable
|
||||
openclaw update --channel beta
|
||||
openclaw update --channel dev
|
||||
```
|
||||
|
||||
这会通过相应的 npm dist-tag（`latest`、`beta`、`dev`）进行更新。
|
||||
|
||||
当你使用 `--channel` **显式**切换渠道时，OpenClaw 还会对齐安装方式：
|
||||
|
||||
- `dev` 确保有一个 git checkout（默认 `~/openclaw`，可通过 `OPENCLAW_GIT_DIR` 覆盖），
|
||||
更新它，并从该 checkout 安装全局 CLI。
|
||||
- `stable`/`beta` 使用匹配的 dist-tag 从 npm 安装。
|
||||
|
||||
提示：如果你想同时使用 stable + dev，保留两个克隆并将 Gateway 网关指向 stable 那个。
|
||||
|
||||
## 插件和渠道
|
||||
|
||||
当你使用 `openclaw update` 切换渠道时，OpenClaw 还会同步插件来源：
|
||||
|
||||
- `dev` 优先使用 git checkout 中的内置插件。
|
||||
- `stable` 和 `beta` 恢复 npm 安装的插件包。
|
||||
|
||||
## 标签最佳实践
|
||||
|
||||
- 为你希望 git checkout 落在的发布版本打标签（`vYYYY.M.D` 或 `vYYYY.M.D-<patch>`）。
|
||||
- 保持标签不可变：永远不要移动或重用标签。
|
||||
- npm dist-tag 仍然是 npm 安装的数据源：
|
||||
- `latest` → stable
|
||||
- `beta` → 候选构建
|
||||
- `dev` → main 快照（可选）
|
||||
|
||||
## macOS 应用可用性
|
||||
|
||||
Beta 和 dev 构建可能**不**包含 macOS 应用发布。这没问题：
|
||||
|
||||
- git 标签和 npm dist-tag 仍然可以发布。
|
||||
- 在发布说明或变更日志中注明"此 beta 无 macOS 构建"。
|
||||
532
content/install/docker.md
Normal file
532
content/install/docker.md
Normal file
@@ -0,0 +1,532 @@
|
||||
---
|
||||
read_when:
|
||||
- 你想要容器化的 Gateway 网关而不是本地安装
|
||||
- 你正在验证 Docker 流程
|
||||
summary: OpenClaw 的可选 Docker 设置和新手引导
|
||||
title: Docker
|
||||
x-i18n:
|
||||
generated_at: "2026-02-03T07:51:20Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: bd823e49b6ce76fe1136a42bf48f436b316ed1cd2f9612e3f4919f1e6b2cdee9
|
||||
source_path: install/docker.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Docker（可选）
|
||||
|
||||
Docker 是**可选的**。仅当你想要容器化的 Gateway 网关或验证 Docker 流程时才使用它。
|
||||
|
||||
## Docker 适合我吗？
|
||||
|
||||
- **是**：你想要一个隔离的、可丢弃的 Gateway 网关环境，或在没有本地安装的主机上运行 OpenClaw。
|
||||
- **否**：你在自己的机器上运行，只想要最快的开发循环。请改用正常的安装流程。
|
||||
- **沙箱注意事项**：智能体沙箱隔离也使用 Docker，但它**不需要**完整的 Gateway 网关在 Docker 中运行。参阅[沙箱隔离](/gateway/sandboxing)。
|
||||
|
||||
本指南涵盖：
|
||||
|
||||
- 容器化 Gateway 网关（完整的 OpenClaw 在 Docker 中）
|
||||
- 每会话智能体沙箱（主机 Gateway 网关 + Docker 隔离的智能体工具）
|
||||
|
||||
沙箱隔离详情：[沙箱隔离](/gateway/sandboxing)
|
||||
|
||||
## 要求
|
||||
|
||||
- Docker Desktop（或 Docker Engine）+ Docker Compose v2
|
||||
- 足够的磁盘空间用于镜像 + 日志
|
||||
|
||||
## 容器化 Gateway 网关（Docker Compose）
|
||||
|
||||
### 快速开始（推荐）
|
||||
|
||||
从仓库根目录：
|
||||
|
||||
```bash
|
||||
./docker-setup.sh
|
||||
```
|
||||
|
||||
此脚本：
|
||||
|
||||
- 构建 Gateway 网关镜像
|
||||
- 运行新手引导向导
|
||||
- 打印可选的提供商设置提示
|
||||
- 通过 Docker Compose 启动 Gateway 网关
|
||||
- 生成 Gateway 网关令牌并写入 `.env`
|
||||
|
||||
可选环境变量：
|
||||
|
||||
- `OPENCLAW_DOCKER_APT_PACKAGES` — 在构建期间安装额外的 apt 包
|
||||
- `OPENCLAW_EXTRA_MOUNTS` — 添加额外的主机绑定挂载
|
||||
- `OPENCLAW_HOME_VOLUME` — 在命名卷中持久化 `/home/node`
|
||||
|
||||
完成后：
|
||||
|
||||
- 在浏览器中打开 `http://127.0.0.1:18789/`。
|
||||
- 将令牌粘贴到控制 UI（设置 → token）。
|
||||
- 需要再次获取带令牌的 URL？运行 `docker compose run --rm openclaw-cli dashboard --no-open`。
|
||||
|
||||
它在主机上写入配置/工作区：
|
||||
|
||||
- `~/.openclaw/`
|
||||
- `~/.openclaw/workspace`
|
||||
|
||||
在 VPS 上运行？参阅 [Hetzner（Docker VPS）](/install/hetzner)。
|
||||
|
||||
### 手动流程（compose）
|
||||
|
||||
```bash
|
||||
docker build -t openclaw:local -f Dockerfile .
|
||||
docker compose run --rm openclaw-cli onboard
|
||||
docker compose up -d openclaw-gateway
|
||||
```
|
||||
|
||||
注意：从仓库根目录运行 `docker compose ...`。如果你启用了 `OPENCLAW_EXTRA_MOUNTS` 或 `OPENCLAW_HOME_VOLUME`，设置脚本会写入 `docker-compose.extra.yml`；在其他地方运行 Compose 时包含它：
|
||||
|
||||
```bash
|
||||
docker compose -f docker-compose.yml -f docker-compose.extra.yml <command>
|
||||
```
|
||||
|
||||
### 控制 UI 令牌 + 配对（Docker）
|
||||
|
||||
如果你看到"unauthorized"或"disconnected (1008): pairing required"，获取新的仪表板链接并批准浏览器设备：
|
||||
|
||||
```bash
|
||||
docker compose run --rm openclaw-cli dashboard --no-open
|
||||
docker compose run --rm openclaw-cli devices list
|
||||
docker compose run --rm openclaw-cli devices approve <requestId>
|
||||
```
|
||||
|
||||
更多详情：[仪表板](/web/dashboard)，[设备](/cli/devices)。
|
||||
|
||||
### 额外挂载（可选）
|
||||
|
||||
如果你想将额外的主机目录挂载到容器中，在运行 `docker-setup.sh` 之前设置 `OPENCLAW_EXTRA_MOUNTS`。这接受逗号分隔的 Docker 绑定挂载列表，并通过生成 `docker-compose.extra.yml` 将它们应用到 `openclaw-gateway` 和 `openclaw-cli`。
|
||||
|
||||
示例：
|
||||
|
||||
```bash
|
||||
export OPENCLAW_EXTRA_MOUNTS="$HOME/.codex:/home/node/.codex:ro,$HOME/github:/home/node/github:rw"
|
||||
./docker-setup.sh
|
||||
```
|
||||
|
||||
注意：
|
||||
|
||||
- 路径必须在 macOS/Windows 上与 Docker Desktop 共享。
|
||||
- 如果你编辑 `OPENCLAW_EXTRA_MOUNTS`，重新运行 `docker-setup.sh` 以重新生成额外的 compose 文件。
|
||||
- `docker-compose.extra.yml` 是生成的。不要手动编辑它。
|
||||
|
||||
### 持久化整个容器 home（可选）
|
||||
|
||||
如果你想让 `/home/node` 在容器重建后持久化，通过 `OPENCLAW_HOME_VOLUME` 设置一个命名卷。这会创建一个 Docker 卷并将其挂载到 `/home/node`，同时保持标准的配置/工作区绑定挂载。这里使用命名卷（不是绑定路径）；对于绑定挂载，使用 `OPENCLAW_EXTRA_MOUNTS`。
|
||||
|
||||
示例：
|
||||
|
||||
```bash
|
||||
export OPENCLAW_HOME_VOLUME="openclaw_home"
|
||||
./docker-setup.sh
|
||||
```
|
||||
|
||||
你可以将其与额外挂载结合使用：
|
||||
|
||||
```bash
|
||||
export OPENCLAW_HOME_VOLUME="openclaw_home"
|
||||
export OPENCLAW_EXTRA_MOUNTS="$HOME/.codex:/home/node/.codex:ro,$HOME/github:/home/node/github:rw"
|
||||
./docker-setup.sh
|
||||
```
|
||||
|
||||
注意：
|
||||
|
||||
- 如果你更改 `OPENCLAW_HOME_VOLUME`，重新运行 `docker-setup.sh` 以重新生成额外的 compose 文件。
|
||||
- 命名卷会持久化直到使用 `docker volume rm <name>` 删除。
|
||||
|
||||
### 安装额外的 apt 包（可选）
|
||||
|
||||
如果你需要镜像内的系统包（例如构建工具或媒体库），在运行 `docker-setup.sh` 之前设置 `OPENCLAW_DOCKER_APT_PACKAGES`。这会在镜像构建期间安装包，因此即使容器被删除它们也会持久化。
|
||||
|
||||
示例：
|
||||
|
||||
```bash
|
||||
export OPENCLAW_DOCKER_APT_PACKAGES="ffmpeg build-essential"
|
||||
./docker-setup.sh
|
||||
```
|
||||
|
||||
注意：
|
||||
|
||||
- 这接受空格分隔的 apt 包名称列表。
|
||||
- 如果你更改 `OPENCLAW_DOCKER_APT_PACKAGES`，重新运行 `docker-setup.sh` 以重建镜像。
|
||||
|
||||
### 高级用户/功能完整的容器（选择加入）
|
||||
|
||||
默认的 Docker 镜像是**安全优先**的，以非 root 的 `node` 用户运行。这保持了较小的攻击面，但这意味着：
|
||||
|
||||
- 运行时无法安装系统包
|
||||
- 默认没有 Homebrew
|
||||
- 没有捆绑的 Chromium/Playwright 浏览器
|
||||
|
||||
如果你想要功能更完整的容器，使用这些选择加入选项：
|
||||
|
||||
1. **持久化 `/home/node`** 以便浏览器下载和工具缓存能够保留：
|
||||
|
||||
```bash
|
||||
export OPENCLAW_HOME_VOLUME="openclaw_home"
|
||||
./docker-setup.sh
|
||||
```
|
||||
|
||||
2. **将系统依赖烘焙到镜像中**（可重复 + 持久化）：
|
||||
|
||||
```bash
|
||||
export OPENCLAW_DOCKER_APT_PACKAGES="git curl jq"
|
||||
./docker-setup.sh
|
||||
```
|
||||
|
||||
3. **不使用 `npx` 安装 Playwright 浏览器**（避免 npm 覆盖冲突）：
|
||||
|
||||
```bash
|
||||
docker compose run --rm openclaw-cli \
|
||||
node /app/node_modules/playwright-core/cli.js install chromium
|
||||
```
|
||||
|
||||
如果你需要 Playwright 安装系统依赖，使用 `OPENCLAW_DOCKER_APT_PACKAGES` 重建镜像，而不是在运行时使用 `--with-deps`。
|
||||
|
||||
4. **持久化 Playwright 浏览器下载**：
|
||||
|
||||
- 在 `docker-compose.yml` 中设置 `PLAYWRIGHT_BROWSERS_PATH=/home/node/.cache/ms-playwright`。
|
||||
- 确保 `/home/node` 通过 `OPENCLAW_HOME_VOLUME` 持久化，或通过 `OPENCLAW_EXTRA_MOUNTS` 挂载 `/home/node/.cache/ms-playwright`。
|
||||
|
||||
### 权限 + EACCES
|
||||
|
||||
镜像以 `node`（uid 1000）运行。如果你在 `/home/node/.openclaw` 上看到权限错误，确保你的主机绑定挂载由 uid 1000 拥有。
|
||||
|
||||
示例（Linux 主机）：
|
||||
|
||||
```bash
|
||||
sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace
|
||||
```
|
||||
|
||||
如果你选择以 root 运行以方便使用，你接受了安全权衡。
|
||||
|
||||
### 更快的重建（推荐）
|
||||
|
||||
要加速重建，排序你的 Dockerfile 以便依赖层被缓存。这避免了除非锁文件更改否则重新运行 `pnpm install`：
|
||||
|
||||
```dockerfile
|
||||
FROM node:22-bookworm
|
||||
|
||||
# 安装 Bun（构建脚本需要）
|
||||
RUN curl -fsSL https://bun.sh/install | bash
|
||||
ENV PATH="/root/.bun/bin:${PATH}"
|
||||
|
||||
RUN corepack enable
|
||||
|
||||
WORKDIR /app
|
||||
|
||||
# 缓存依赖，除非包元数据更改
|
||||
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
|
||||
COPY ui/package.json ./ui/package.json
|
||||
COPY scripts ./scripts
|
||||
|
||||
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"]
|
||||
```
|
||||
|
||||
### 渠道设置（可选）
|
||||
|
||||
使用 CLI 容器配置渠道，然后在需要时重启 Gateway 网关。
|
||||
|
||||
WhatsApp（QR）：
|
||||
|
||||
```bash
|
||||
docker compose run --rm openclaw-cli channels login
|
||||
```
|
||||
|
||||
Telegram（bot token）：
|
||||
|
||||
```bash
|
||||
docker compose run --rm openclaw-cli channels add --channel telegram --token "<token>"
|
||||
```
|
||||
|
||||
Discord（bot token）：
|
||||
|
||||
```bash
|
||||
docker compose run --rm openclaw-cli channels add --channel discord --token "<token>"
|
||||
```
|
||||
|
||||
文档：[WhatsApp](/channels/whatsapp)，[Telegram](/channels/telegram)，[Discord](/channels/discord)
|
||||
|
||||
### OpenAI Codex OAuth（无头 Docker）
|
||||
|
||||
如果你在向导中选择 OpenAI Codex OAuth，它会打开浏览器 URL 并尝试在 `http://127.0.0.1:1455/auth/callback` 捕获回调。在 Docker 或无头设置中，该回调可能显示浏览器错误。复制你到达的完整重定向 URL 并将其粘贴回向导以完成认证。
|
||||
|
||||
### 健康检查
|
||||
|
||||
```bash
|
||||
docker compose exec openclaw-gateway node dist/index.js health --token "$OPENCLAW_GATEWAY_TOKEN"
|
||||
```
|
||||
|
||||
### E2E 冒烟测试（Docker）
|
||||
|
||||
```bash
|
||||
scripts/e2e/onboard-docker.sh
|
||||
```
|
||||
|
||||
### QR 导入冒烟测试（Docker）
|
||||
|
||||
```bash
|
||||
pnpm test:docker:qr
|
||||
```
|
||||
|
||||
### 注意
|
||||
|
||||
- Gateway 网关绑定默认为 `lan` 用于容器使用。
|
||||
- Dockerfile CMD 使用 `--allow-unconfigured`；挂载的配置如果 `gateway.mode` 不是 `local` 仍会启动。覆盖 CMD 以强制执行检查。
|
||||
- Gateway 网关容器是会话的真实来源（`~/.openclaw/agents/<agentId>/sessions/`）。
|
||||
|
||||
## 智能体沙箱（主机 Gateway 网关 + Docker 工具）
|
||||
|
||||
深入了解：[沙箱隔离](/gateway/sandboxing)
|
||||
|
||||
### 它做什么
|
||||
|
||||
当启用 `agents.defaults.sandbox` 时，**非主会话**在 Docker 容器内运行工具。Gateway 网关保持在你的主机上，但工具执行是隔离的：
|
||||
|
||||
- scope：默认为 `"agent"`（每个智能体一个容器 + 工作区）
|
||||
- scope：`"session"` 用于每会话隔离
|
||||
- 每作用域工作区文件夹挂载在 `/workspace`
|
||||
- 可选的智能体工作区访问（`agents.defaults.sandbox.workspaceAccess`）
|
||||
- 允许/拒绝工具策略（拒绝优先）
|
||||
- 入站媒体被复制到活动沙箱工作区（`media/inbound/*`），以便工具可以读取它（使用 `workspaceAccess: "rw"` 时，这会落在智能体工作区中）
|
||||
|
||||
警告：`scope: "shared"` 禁用跨会话隔离。所有会话共享一个容器和一个工作区。
|
||||
|
||||
### 每智能体沙箱配置文件（多智能体）
|
||||
|
||||
如果你使用多智能体路由，每个智能体可以覆盖沙箱 + 工具设置：`agents.list[].sandbox` 和 `agents.list[].tools`（加上 `agents.list[].tools.sandbox.tools`）。这让你可以在一个 Gateway 网关中运行混合访问级别：
|
||||
|
||||
- 完全访问（个人智能体）
|
||||
- 只读工具 + 只读工作区（家庭/工作智能体）
|
||||
- 无文件系统/shell 工具（公共智能体）
|
||||
|
||||
参阅[多智能体沙箱与工具](/tools/multi-agent-sandbox-tools)了解示例、优先级和故障排除。
|
||||
|
||||
### 默认行为
|
||||
|
||||
- 镜像：`openclaw-sandbox:bookworm-slim`
|
||||
- 每个智能体一个容器
|
||||
- 智能体工作区访问：`workspaceAccess: "none"`（默认）使用 `~/.openclaw/sandboxes`
|
||||
- `"ro"` 保持沙箱工作区在 `/workspace` 并将智能体工作区只读挂载在 `/agent`（禁用 `write`/`edit`/`apply_patch`）
|
||||
- `"rw"` 将智能体工作区读写挂载在 `/workspace`
|
||||
- 自动清理：空闲 > 24h 或 年龄 > 7d
|
||||
- 网络：默认为 `none`（如果需要出站则明确选择加入）
|
||||
- 默认允许：`exec`、`process`、`read`、`write`、`edit`、`sessions_list`、`sessions_history`、`sessions_send`、`sessions_spawn`、`session_status`
|
||||
- 默认拒绝：`browser`、`canvas`、`nodes`、`cron`、`discord`、`gateway`
|
||||
|
||||
### 启用沙箱隔离
|
||||
|
||||
如果你计划在 `setupCommand` 中安装包，请注意：
|
||||
|
||||
- 默认 `docker.network` 是 `"none"`（无出站）。
|
||||
- `readOnlyRoot: true` 阻止包安装。
|
||||
- `user` 必须是 root 才能运行 `apt-get`（省略 `user` 或设置 `user: "0:0"`）。
|
||||
当 `setupCommand`（或 docker 配置）更改时，OpenClaw 会自动重建容器，除非容器是**最近使用的**（在约 5 分钟内）。热容器会记录警告，包含确切的 `openclaw sandbox recreate ...` 命令。
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
sandbox: {
|
||||
mode: "non-main", // off | non-main | all
|
||||
scope: "agent", // session | agent | shared（默认为 agent）
|
||||
workspaceAccess: "none", // none | ro | rw
|
||||
workspaceRoot: "~/.openclaw/sandboxes",
|
||||
docker: {
|
||||
image: "openclaw-sandbox:bookworm-slim",
|
||||
workdir: "/workspace",
|
||||
readOnlyRoot: true,
|
||||
tmpfs: ["/tmp", "/var/tmp", "/run"],
|
||||
network: "none",
|
||||
user: "1000:1000",
|
||||
capDrop: ["ALL"],
|
||||
env: { LANG: "C.UTF-8" },
|
||||
setupCommand: "apt-get update && apt-get install -y git curl jq",
|
||||
pidsLimit: 256,
|
||||
memory: "1g",
|
||||
memorySwap: "2g",
|
||||
cpus: 1,
|
||||
ulimits: {
|
||||
nofile: { soft: 1024, hard: 2048 },
|
||||
nproc: 256,
|
||||
},
|
||||
seccompProfile: "/path/to/seccomp.json",
|
||||
apparmorProfile: "openclaw-sandbox",
|
||||
dns: ["1.1.1.1", "8.8.8.8"],
|
||||
extraHosts: ["internal.service:10.0.0.5"],
|
||||
},
|
||||
prune: {
|
||||
idleHours: 24, // 0 禁用空闲清理
|
||||
maxAgeDays: 7, // 0 禁用最大年龄清理
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
tools: {
|
||||
sandbox: {
|
||||
tools: {
|
||||
allow: [
|
||||
"exec",
|
||||
"process",
|
||||
"read",
|
||||
"write",
|
||||
"edit",
|
||||
"sessions_list",
|
||||
"sessions_history",
|
||||
"sessions_send",
|
||||
"sessions_spawn",
|
||||
"session_status",
|
||||
],
|
||||
deny: ["browser", "canvas", "nodes", "cron", "discord", "gateway"],
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
加固选项位于 `agents.defaults.sandbox.docker` 下：`network`、`user`、`pidsLimit`、`memory`、`memorySwap`、`cpus`、`ulimits`、`seccompProfile`、`apparmorProfile`、`dns`、`extraHosts`。
|
||||
|
||||
多智能体：通过 `agents.list[].sandbox.{docker,browser,prune}.*` 按智能体覆盖 `agents.defaults.sandbox.{docker,browser,prune}.*`（当 `agents.defaults.sandbox.scope` / `agents.list[].sandbox.scope` 是 `"shared"` 时忽略）。
|
||||
|
||||
### 构建默认沙箱镜像
|
||||
|
||||
```bash
|
||||
scripts/sandbox-setup.sh
|
||||
```
|
||||
|
||||
这使用 `Dockerfile.sandbox` 构建 `openclaw-sandbox:bookworm-slim`。
|
||||
|
||||
### 沙箱通用镜像（可选）
|
||||
|
||||
如果你想要一个带有常见构建工具（Node、Go、Rust 等）的沙箱镜像，构建通用镜像：
|
||||
|
||||
```bash
|
||||
scripts/sandbox-common-setup.sh
|
||||
```
|
||||
|
||||
这构建 `openclaw-sandbox-common:bookworm-slim`。要使用它：
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
sandbox: { docker: { image: "openclaw-sandbox-common:bookworm-slim" } },
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### 沙箱浏览器镜像
|
||||
|
||||
要在沙箱内运行浏览器工具，构建浏览器镜像：
|
||||
|
||||
```bash
|
||||
scripts/sandbox-browser-setup.sh
|
||||
```
|
||||
|
||||
这使用 `Dockerfile.sandbox-browser` 构建 `openclaw-sandbox-browser:bookworm-slim`。容器运行启用 CDP 的 Chromium 和可选的 noVNC 观察器（通过 Xvfb 有头）。
|
||||
|
||||
注意：
|
||||
|
||||
- 有头（Xvfb）比无头减少机器人阻止。
|
||||
- 通过设置 `agents.defaults.sandbox.browser.headless=true` 仍然可以使用无头模式。
|
||||
- 不需要完整的桌面环境（GNOME）；Xvfb 提供显示。
|
||||
|
||||
使用配置：
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
sandbox: {
|
||||
browser: { enabled: true },
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
自定义浏览器镜像：
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
sandbox: { browser: { image: "my-openclaw-browser" } },
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
启用后，智能体接收：
|
||||
|
||||
- 沙箱浏览器控制 URL（用于 `browser` 工具）
|
||||
- noVNC URL（如果启用且 headless=false）
|
||||
|
||||
记住：如果你使用工具允许列表，添加 `browser`（并从拒绝中移除它）否则工具仍然被阻止。
|
||||
清理规则（`agents.defaults.sandbox.prune`）也适用于浏览器容器。
|
||||
|
||||
### 自定义沙箱镜像
|
||||
|
||||
构建你自己的镜像并将配置指向它：
|
||||
|
||||
```bash
|
||||
docker build -t my-openclaw-sbx -f Dockerfile.sandbox .
|
||||
```
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
sandbox: { docker: { image: "my-openclaw-sbx" } },
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### 工具策略（允许/拒绝）
|
||||
|
||||
- `deny` 优先于 `allow`。
|
||||
- 如果 `allow` 为空：所有工具（除了 deny）都可用。
|
||||
- 如果 `allow` 非空：只有 `allow` 中的工具可用（减去 deny）。
|
||||
|
||||
### 清理策略
|
||||
|
||||
两个选项：
|
||||
|
||||
- `prune.idleHours`：移除 X 小时未使用的容器（0 = 禁用）
|
||||
- `prune.maxAgeDays`：移除超过 X 天的容器（0 = 禁用）
|
||||
|
||||
示例：
|
||||
|
||||
- 保留繁忙会话但限制生命周期：
|
||||
`idleHours: 24`、`maxAgeDays: 7`
|
||||
- 永不清理：
|
||||
`idleHours: 0`、`maxAgeDays: 0`
|
||||
|
||||
### 安全注意事项
|
||||
|
||||
- 硬隔离仅适用于**工具**（exec/read/write/edit/apply_patch）。
|
||||
- 仅主机工具如 browser/camera/canvas 默认被阻止。
|
||||
- 在沙箱中允许 `browser` **会破坏隔离**（浏览器在主机上运行）。
|
||||
|
||||
## 故障排除
|
||||
|
||||
- 镜像缺失：使用 [`scripts/sandbox-setup.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/sandbox-setup.sh) 构建或设置 `agents.defaults.sandbox.docker.image`。
|
||||
- 容器未运行：它会按需为每个会话自动创建。
|
||||
- 沙箱中的权限错误：将 `docker.user` 设置为与你挂载的工作区所有权匹配的 UID:GID（或 chown 工作区文件夹）。
|
||||
- 找不到自定义工具：OpenClaw 使用 `sh -lc`（登录 shell）运行命令，这会 source `/etc/profile` 并可能重置 PATH。设置 `docker.env.PATH` 以在前面添加你的自定义工具路径（例如 `/custom/bin:/usr/local/share/npm-global/bin`），或在你的 Dockerfile 中在 `/etc/profile.d/` 下添加脚本。
|
||||
127
content/install/exe-dev.md
Normal file
127
content/install/exe-dev.md
Normal file
@@ -0,0 +1,127 @@
|
||||
---
|
||||
read_when:
|
||||
- 你想要一个便宜的常驻 Linux 主机来运行 Gateway 网关
|
||||
- 你想要远程控制 UI 访问而无需运行自己的 VPS
|
||||
summary: 在 exe.dev 上运行 OpenClaw Gateway 网关（VM + HTTPS 代理）以实现远程访问
|
||||
title: exe.dev
|
||||
x-i18n:
|
||||
generated_at: "2026-02-03T07:51:36Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: 8d57ee7dd6029f0b778465c147092b824a0f1b0680af13032aaf116ff3d4d671
|
||||
source_path: platforms/exe-dev.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# exe.dev
|
||||
|
||||
目标：OpenClaw Gateway 网关运行在 exe.dev VM 上，可从你的笔记本电脑通过以下地址访问：`https://<vm-name>.exe.xyz`
|
||||
|
||||
本页假设使用 exe.dev 的默认 **exeuntu** 镜像。如果你选择了不同的发行版，请相应地映射软件包。
|
||||
|
||||
## 新手快速路径
|
||||
|
||||
1. [https://exe.new/openclaw](https://exe.new/openclaw)
|
||||
2. 根据需要填写你的认证密钥/令牌
|
||||
3. 点击 VM 旁边的"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) 创建 VM
|
||||
|
||||
从你的设备：
|
||||
|
||||
```bash
|
||||
ssh exe.dev new
|
||||
```
|
||||
|
||||
然后连接：
|
||||
|
||||
```bash
|
||||
ssh <vm-name>.exe.xyz
|
||||
```
|
||||
|
||||
提示：保持此 VM **有状态**。OpenClaw 在 `~/.openclaw/` 和 `~/.openclaw/workspace/` 下存储状态。
|
||||
|
||||
## 2) 安装先决条件（在 VM 上）
|
||||
|
||||
```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`（参阅新手引导中的控制 UI 输出）。使用 `openclaw devices list` 和 `openclaw devices approve <requestId>` 批准设备。如有疑问，从浏览器使用 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
content/install/fly.md
Normal file
490
content/install/fly.md
Normal file
@@ -0,0 +1,490 @@
|
||||
---
|
||||
description: Deploy OpenClaw on Fly.io
|
||||
title: Fly.io
|
||||
x-i18n:
|
||||
generated_at: "2026-02-03T07:52:55Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: a00bae43e416112eb269126445c51492a30abe9e136d89e161fc4193314a876f
|
||||
source_path: platforms/fly.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Fly.io 部署
|
||||
|
||||
**目标：** OpenClaw Gateway 网关运行在 [Fly.io](https://fly.io) 机器上，具有持久存储、自动 HTTPS 和 Discord/渠道访问。
|
||||
|
||||
## 你需要什么
|
||||
|
||||
- 已安装 [flyctl CLI](https://fly.io/docs/hands-on/install-flyctl/)
|
||||
- Fly.io 账户（免费套餐可用）
|
||||
- 模型认证：Anthropic API 密钥（或其他提供商密钥）
|
||||
- 渠道凭证：Discord bot token、Telegram token 等
|
||||
|
||||
## 初学者快速路径
|
||||
|
||||
1. 克隆仓库 → 自定义 `fly.toml`
|
||||
2. 创建应用 + 卷 → 设置密钥
|
||||
3. 使用 `fly deploy` 部署
|
||||
4. SSH 进入创建配置或使用 Control UI
|
||||
|
||||
## 1）创建 Fly 应用
|
||||
|
||||
```bash
|
||||
# Clone the repo
|
||||
git clone https://github.com/openclaw/openclaw.git
|
||||
cd openclaw
|
||||
|
||||
# Create a new Fly app (pick your own name)
|
||||
fly apps create my-openclaw
|
||||
|
||||
# Create a persistent volume (1GB is usually enough)
|
||||
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" # Your app name
|
||||
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
|
||||
# Required: Gateway token (for non-loopback binding)
|
||||
fly secrets set OPENCLAW_GATEWAY_TOKEN=$(openssl rand -hex 32)
|
||||
|
||||
# Model provider API keys
|
||||
fly secrets set ANTHROPIC_API_KEY=sk-ant-...
|
||||
|
||||
# Optional: Other providers
|
||||
fly secrets set OPENAI_API_KEY=sk-...
|
||||
fly secrets set GOOGLE_API_KEY=...
|
||||
|
||||
# Channel tokens
|
||||
fly secrets set DISCORD_BOT_TOKEN=MTQ...
|
||||
```
|
||||
|
||||
**注意事项：**
|
||||
|
||||
- 非 loopback 绑定（`--bind lan`）出于安全需要 `OPENCLAW_GATEWAY_TOKEN`。
|
||||
- 像对待密码一样对待这些 token。
|
||||
- **优先使用环境变量而不是配置文件**来存储所有 API 密钥和 token。这可以避免密钥出现在 `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 token 可以来自：
|
||||
|
||||
- 环境变量：`DISCORD_BOT_TOKEN`（推荐用于密钥）
|
||||
- 配置文件：`channels.discord.token`
|
||||
|
||||
如果使用环境变量，无需将 token 添加到配置中。Gateway 网关会自动读取 `DISCORD_BOT_TOKEN`。
|
||||
|
||||
重启以应用：
|
||||
|
||||
```bash
|
||||
exit
|
||||
fly machine restart <machine-id>
|
||||
```
|
||||
|
||||
## 6）访问 Gateway 网关
|
||||
|
||||
### Control UI
|
||||
|
||||
在浏览器中打开：
|
||||
|
||||
```bash
|
||||
fly open
|
||||
```
|
||||
|
||||
或访问 `https://my-openclaw.fly.dev/`
|
||||
|
||||
粘贴你的 Gateway 网关 token（来自 `OPENCLAW_GATEWAY_TOKEN` 的那个）进行认证。
|
||||
|
||||
### 日志
|
||||
|
||||
```bash
|
||||
fly logs # Live logs
|
||||
fly logs --no-tail # Recent logs
|
||||
```
|
||||
|
||||
### 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
|
||||
# Use echo + tee (pipe from local to remote)
|
||||
echo '{"your":"config"}' | fly ssh console -C "tee /data/openclaw.json"
|
||||
|
||||
# Or use 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
|
||||
# Pull latest changes
|
||||
git pull
|
||||
|
||||
# Redeploy
|
||||
fly deploy
|
||||
|
||||
# Check health
|
||||
fly status
|
||||
fly logs
|
||||
```
|
||||
|
||||
### 更新机器命令
|
||||
|
||||
如果你需要更改启动命令而无需完全重新部署：
|
||||
|
||||
```bash
|
||||
# Get machine ID
|
||||
fly machines list
|
||||
|
||||
# Update command
|
||||
fly machine update <machine-id> --command "node dist/index.js gateway --port 3000 --bind lan" -y
|
||||
|
||||
# Or with memory increase
|
||||
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 等）发现。
|
||||
|
||||
对于**无公共暴露**的加固部署，使用私有模板。
|
||||
|
||||
### 何时使用私有部署
|
||||
|
||||
- 你只进行**出站**调用/消息（无入站 webhooks）
|
||||
- 你使用 **ngrok 或 Tailscale** 隧道处理任何 webhook 回调
|
||||
- 你通过 **SSH、代理或 WireGuard** 而不是浏览器访问 Gateway 网关
|
||||
- 你希望部署**对互联网扫描器隐藏**
|
||||
|
||||
### 设置
|
||||
|
||||
使用 `fly.private.toml` 替代标准配置：
|
||||
|
||||
```bash
|
||||
# Deploy with private config
|
||||
fly deploy -c fly.private.toml
|
||||
```
|
||||
|
||||
或转换现有部署：
|
||||
|
||||
```bash
|
||||
# List current IPs
|
||||
fly ips list -a my-openclaw
|
||||
|
||||
# Release public IPs
|
||||
fly ips release <public-ipv4> -a my-openclaw
|
||||
fly ips release <public-ipv6> -a my-openclaw
|
||||
|
||||
# Switch to private config so future deploys don't re-allocate public IPs
|
||||
# (remove [http_service] or deploy with the private template)
|
||||
fly deploy -c fly.private.toml
|
||||
|
||||
# Allocate private-only 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
|
||||
# Forward local port 3000 to the app
|
||||
fly proxy 3000:3000 -a my-openclaw
|
||||
|
||||
# Then open http://localhost:3000 in browser
|
||||
```
|
||||
|
||||
**选项 2：WireGuard VPN**
|
||||
|
||||
```bash
|
||||
# Create WireGuard config (one-time)
|
||||
fly wireguard create
|
||||
|
||||
# Import to WireGuard client, then access via internal IPv6
|
||||
# Example: http://[fdaa:x:x:x:x::x]:3000
|
||||
```
|
||||
|
||||
**选项 3：仅 SSH**
|
||||
|
||||
```bash
|
||||
fly ssh console -a my-openclaw
|
||||
```
|
||||
|
||||
### 私有部署的 Webhooks
|
||||
|
||||
如果你需要 webhook 回调（Twilio、Telnyx 等）而不暴露公共：
|
||||
|
||||
1. **ngrok 隧道** - 在容器内或作为 sidecar 运行 ngrok
|
||||
2. **Tailscale Funnel** - 通过 Tailscale 暴露特定路径
|
||||
3. **仅出站** - 某些提供商（Twilio）对于出站呼叫无需 webhooks 也能正常工作
|
||||
|
||||
使用 ngrok 的示例语音通话配置：
|
||||
|
||||
```json
|
||||
{
|
||||
"plugins": {
|
||||
"entries": {
|
||||
"voice-call": {
|
||||
"enabled": true,
|
||||
"config": {
|
||||
"provider": "twilio",
|
||||
"tunnel": { "provider": "ngrok" }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
ngrok 隧道在容器内运行并提供公共 webhook URL，而不暴露 Fly 应用本身。
|
||||
|
||||
### 安全优势
|
||||
|
||||
| 方面 | 公共 | 私有 |
|
||||
| --------------- | ------ | -------- |
|
||||
| 互联网扫描器 | 可发现 | 隐藏 |
|
||||
| 直接攻击 | 可能 | 被阻止 |
|
||||
| Control 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
content/install/gcp.md
Normal file
510
content/install/gcp.md
Normal file
@@ -0,0 +1,510 @@
|
||||
---
|
||||
read_when:
|
||||
- 你想在 GCP 上 24/7 运行 OpenClaw
|
||||
- 你想要在自己的 VM 上运行生产级、常驻的 Gateway 网关
|
||||
- 你想完全控制持久化、二进制文件和重启行为
|
||||
summary: 在 GCP Compute Engine VM（Docker）上 24/7 运行 OpenClaw Gateway 网关并持久化状态
|
||||
title: GCP
|
||||
x-i18n:
|
||||
generated_at: "2026-02-03T07:52:50Z"
|
||||
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 VM 上运行持久化的 OpenClaw Gateway 网关，具有持久状态、内置二进制文件和安全的重启行为。
|
||||
|
||||
如果你想要"OpenClaw 24/7 大约 $5-12/月"，这是在 Google Cloud 上的可靠设置。
|
||||
价格因机器类型和区域而异；选择适合你工作负载的最小 VM，如果遇到 OOM 则扩容。
|
||||
|
||||
## 我们在做什么（简单说明）？
|
||||
|
||||
- 创建 GCP 项目并启用计费
|
||||
- 创建 Compute Engine VM
|
||||
- 安装 Docker（隔离的应用运行时）
|
||||
- 在 Docker 中启动 OpenClaw Gateway 网关
|
||||
- 在主机上持久化 `~/.openclaw` + `~/.openclaw/workspace`（重启/重建后仍保留）
|
||||
- 通过 SSH 隧道从你的笔记本电脑访问控制 UI
|
||||
|
||||
Gateway 网关可以通过以下方式访问：
|
||||
|
||||
- 从你的笔记本电脑进行 SSH 端口转发
|
||||
- 如果你自己管理防火墙和令牌，可以直接暴露端口
|
||||
|
||||
本指南使用 GCP Compute Engine 上的 Debian。
|
||||
Ubuntu 也可以；请相应地映射软件包。
|
||||
有关通用 Docker 流程，请参阅 [Docker](/install/docker)。
|
||||
|
||||
---
|
||||
|
||||
## 快速路径（有经验的运维人员）
|
||||
|
||||
1. 创建 GCP 项目 + 启用 Compute Engine API
|
||||
2. 创建 Compute Engine VM（e2-small，Debian 12，20GB）
|
||||
3. SSH 进入 VM
|
||||
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 QR
|
||||
- Telegram bot token
|
||||
- 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 UI 完成
|
||||
|
||||
---
|
||||
|
||||
## 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" > Enable
|
||||
|
||||
---
|
||||
|
||||
## 3) 创建 VM
|
||||
|
||||
**机器类型：**
|
||||
|
||||
| 类型 | 配置 | 成本 | 说明 |
|
||||
| -------- | ----------------------- | ---------- | -------------- |
|
||||
| e2-small | 2 vCPU，2GB RAM | ~$12/月 | 推荐 |
|
||||
| e2-micro | 2 vCPU（共享），1GB RAM | 符合免费层 | 负载下可能 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. Name：`openclaw-gateway`
|
||||
3. Region：`us-central1`，Zone：`us-central1-a`
|
||||
4. Machine type：`e2-small`
|
||||
5. Boot disk：Debian 12，20GB
|
||||
6. Create
|
||||
|
||||
---
|
||||
|
||||
## 4) SSH 进入 VM
|
||||
|
||||
**CLI：**
|
||||
|
||||
```bash
|
||||
gcloud compute ssh openclaw-gateway --zone=us-central1-a
|
||||
```
|
||||
|
||||
**Console：**
|
||||
|
||||
在 Compute Engine 仪表板中点击 VM 旁边的"SSH"按钮。
|
||||
|
||||
注意：VM 创建后 SSH 密钥传播可能需要 1-2 分钟。如果连接被拒绝，请等待并重试。
|
||||
|
||||
---
|
||||
|
||||
## 5) 安装 Docker（在 VM 上）
|
||||
|
||||
```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:
|
||||
# 推荐：在 VM 上保持 Gateway 网关仅绑定 loopback；通过 SSH 隧道访问。
|
||||
# 要公开暴露，移除 `127.0.0.1:` 前缀并相应配置防火墙。
|
||||
- "127.0.0.1:${OPENCLAW_GATEWAY_PORT}:18789"
|
||||
|
||||
# 可选：仅当你针对此 VM 运行 iOS/Android 节点并需要 Canvas 主机时。
|
||||
# 如果你公开暴露此端口，请阅读 /gateway/security 并相应配置防火墙。
|
||||
# - "18793:18793"
|
||||
command:
|
||||
[
|
||||
"node",
|
||||
"dist/index.js",
|
||||
"gateway",
|
||||
"--bind",
|
||||
"${OPENCLAW_GATEWAY_BIND}",
|
||||
"--port",
|
||||
"${OPENCLAW_GATEWAY_PORT}",
|
||||
]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10) 将所需二进制文件内置到镜像中（关键）
|
||||
|
||||
在运行中的容器内安装二进制文件是一个陷阱。
|
||||
任何在运行时安装的内容在重启后都会丢失。
|
||||
|
||||
所有 Skills 所需的外部二进制文件必须在镜像构建时安装。
|
||||
|
||||
以下示例仅显示三个常见的二进制文件：
|
||||
|
||||
- `gog` 用于 Gmail 访问
|
||||
- `goplaces` 用于 Google Places
|
||||
- `wacli` 用于 WhatsApp
|
||||
|
||||
这些是示例，不是完整列表。
|
||||
你可以使用相同的模式安装任意数量的二进制文件。
|
||||
|
||||
如果你以后添加依赖额外二进制文件的新 Skills，你必须：
|
||||
|
||||
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 密钥 |
|
||||
| Skill 配置 | `/home/node/.openclaw/skills/` | 主机卷挂载 | Skill 级别状态 |
|
||||
| 智能体工作区 | `/home/node/.openclaw/workspace/` | 主机卷挂载 | 代码和智能体产物 |
|
||||
| WhatsApp 会话 | `/home/node/.openclaw/` | 主机卷挂载 | 保留 QR 登录 |
|
||||
| Gmail 密钥环 | `/home/node/.openclaw/` | 主机卷 + 密码 | 需要 `GOG_KEYRING_PASSWORD` |
|
||||
| 外部二进制文件 | `/usr/local/bin/` | Docker 镜像 | 必须在构建时内置 |
|
||||
| Node 运行时 | 容器文件系统 | Docker 镜像 | 每次镜像构建时重建 |
|
||||
| OS 包 | 容器文件系统 | Docker 镜像 | 不要在运行时安装 |
|
||||
| Docker 容器 | 临时 | 可重启 | 可以安全销毁 |
|
||||
|
||||
---
|
||||
|
||||
## 更新
|
||||
|
||||
在 VM 上更新 OpenClaw：
|
||||
|
||||
```bash
|
||||
cd ~/openclaw
|
||||
git pull
|
||||
docker compose build
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 故障排除
|
||||
|
||||
**SSH 连接被拒绝**
|
||||
|
||||
VM 创建后 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
|
||||
# 首先停止 VM
|
||||
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
|
||||
|
||||
# 启动 VM
|
||||
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 角色。使用最小权限原则。
|
||||
|
||||
参阅 https://cloud.google.com/iam/docs/understanding-roles 了解 IAM 角色详情。
|
||||
|
||||
---
|
||||
|
||||
## 下一步
|
||||
|
||||
- 设置消息渠道：[渠道](/channels)
|
||||
- 将本地设备配对为节点：[节点](/nodes)
|
||||
- 配置 Gateway 网关：[Gateway 网关配置](/gateway/configuration)
|
||||
337
content/install/hetzner.md
Normal file
337
content/install/hetzner.md
Normal file
@@ -0,0 +1,337 @@
|
||||
---
|
||||
read_when:
|
||||
- 你想让 OpenClaw 在云 VPS 上 24/7 运行（而不是你的笔记本电脑）
|
||||
- 你想在自己的 VPS 上运行生产级、永久在线的 Gateway 网关
|
||||
- 你想完全控制持久化、二进制文件和重启行为
|
||||
- 你在 Hetzner 或类似提供商上用 Docker 运行 OpenClaw
|
||||
summary: 在廉价的 Hetzner VPS（Docker）上 24/7 运行 OpenClaw Gateway 网关，带持久状态和内置二进制文件
|
||||
title: Hetzner
|
||||
x-i18n:
|
||||
generated_at: "2026-02-03T07:52:17Z"
|
||||
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 24/7"，这是最简单可靠的设置。
|
||||
Hetzner 定价会变化；选择最小的 Debian/Ubuntu VPS，如果遇到 OOM 再扩容。
|
||||
|
||||
## 我们在做什么（简单说明）？
|
||||
|
||||
- 租用一台小型 Linux 服务器（Hetzner VPS）
|
||||
- 安装 Docker（隔离的应用运行时）
|
||||
- 在 Docker 中启动 OpenClaw Gateway 网关
|
||||
- 在主机上持久化 `~/.openclaw` + `~/.openclaw/workspace`（重启/重建后保留）
|
||||
- 通过 SSH 隧道从你的笔记本电脑访问控制 UI
|
||||
|
||||
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 上保持 Gateway 网关仅限 loopback；通过 SSH 隧道访问。
|
||||
# 要公开暴露，移除 `127.0.0.1:` 前缀并相应配置防火墙。
|
||||
- "127.0.0.1:${OPENCLAW_GATEWAY_PORT}:18789"
|
||||
|
||||
# 可选：仅当你对此 VPS 运行 iOS/Android 节点并需要 Canvas 主机时。
|
||||
# 如果你公开暴露此端口，请阅读 /gateway/security 并相应配置防火墙。
|
||||
# - "18793:18793"
|
||||
command:
|
||||
[
|
||||
"node",
|
||||
"dist/index.js",
|
||||
"gateway",
|
||||
"--bind",
|
||||
"${OPENCLAW_GATEWAY_BIND}",
|
||||
"--port",
|
||||
"${OPENCLAW_GATEWAY_PORT}",
|
||||
]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7) 将所需二进制文件烘焙到镜像中（关键）
|
||||
|
||||
在运行中的容器内安装二进制文件是一个陷阱。
|
||||
任何在运行时安装的东西都会在重启时丢失。
|
||||
|
||||
所有 skills 所需的外部二进制文件必须在镜像构建时安装。
|
||||
|
||||
以下示例仅展示三个常见二进制文件：
|
||||
|
||||
- `gog` 用于 Gmail 访问
|
||||
- `goplaces` 用于 Google Places
|
||||
- `wacli` 用于 WhatsApp
|
||||
|
||||
这些是示例，不是完整列表。
|
||||
你可以使用相同的模式安装任意数量的二进制文件。
|
||||
|
||||
如果你以后添加依赖额外二进制文件的新 skills，你必须：
|
||||
|
||||
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 密钥 |
|
||||
| Skill 配置 | `/home/node/.openclaw/skills/` | 主机卷挂载 | Skill 级别状态 |
|
||||
| 智能体工作区 | `/home/node/.openclaw/workspace/` | 主机卷挂载 | 代码和智能体产物 |
|
||||
| WhatsApp 会话 | `/home/node/.openclaw/` | 主机卷挂载 | 保留二维码登录 |
|
||||
| Gmail 密钥环 | `/home/node/.openclaw/` | 主机卷 + 密码 | 需要 `GOG_KEYRING_PASSWORD` |
|
||||
| 外部二进制文件 | `/usr/local/bin/` | Docker 镜像 | 必须在构建时烘焙 |
|
||||
| Node 运行时 | 容器文件系统 | Docker 镜像 | 每次镜像构建时重建 |
|
||||
| 操作系统包 | 容器文件系统 | Docker 镜像 | 不要在运行时安装 |
|
||||
| Docker 容器 | 临时的 | 可重启 | 可以安全销毁 |
|
||||
193
content/install/index.md
Normal file
193
content/install/index.md
Normal file
@@ -0,0 +1,193 @@
|
||||
---
|
||||
read_when:
|
||||
- 安装 OpenClaw
|
||||
- 你想从 GitHub 安装
|
||||
summary: 安装 OpenClaw（推荐安装器、全局安装或从源代码安装）
|
||||
title: 安装
|
||||
x-i18n:
|
||||
generated_at: "2026-02-03T10:07:43Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: b26f48c116c26c163ee0090fb4c3e29622951bd427ecaeccba7641d97cfdf17a
|
||||
source_path: install/index.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 安装
|
||||
|
||||
除非有特殊原因，否则请使用安装器。它会设置 CLI 并运行新手引导。
|
||||
|
||||
## 快速安装（推荐）
|
||||
|
||||
```bash
|
||||
curl -fsSL https://openclaw.ai/install.sh | bash
|
||||
```
|
||||
|
||||
Windows（PowerShell）：
|
||||
|
||||
```powershell
|
||||
iwr -useb https://openclaw.ai/install.ps1 | iex
|
||||
```
|
||||
|
||||
下一步（如果你跳过了新手引导）：
|
||||
|
||||
```bash
|
||||
openclaw onboard --install-daemon
|
||||
```
|
||||
|
||||
## 系统要求
|
||||
|
||||
- **Node >=22**
|
||||
- macOS、Linux 或通过 WSL2 的 Windows
|
||||
- `pnpm` 仅在从源代码构建时需要
|
||||
|
||||
## 选择安装路径
|
||||
|
||||
### 1）安装器脚本（推荐）
|
||||
|
||||
通过 npm 全局安装 `openclaw` 并运行新手引导。
|
||||
|
||||
```bash
|
||||
curl -fsSL https://openclaw.ai/install.sh | bash
|
||||
```
|
||||
|
||||
安装器标志：
|
||||
|
||||
```bash
|
||||
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --help
|
||||
```
|
||||
|
||||
详情：[安装器内部原理](/install/installer)。
|
||||
|
||||
非交互式（跳过新手引导）：
|
||||
|
||||
```bash
|
||||
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard
|
||||
```
|
||||
|
||||
### 2）全局安装（手动）
|
||||
|
||||
如果你已经有 Node：
|
||||
|
||||
```bash
|
||||
npm install -g openclaw@latest
|
||||
```
|
||||
|
||||
如果你全局安装了 libvips（macOS 上通过 Homebrew 安装很常见）且 `sharp` 安装失败，请强制使用预构建二进制文件：
|
||||
|
||||
```bash
|
||||
SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest
|
||||
```
|
||||
|
||||
如果你看到 `sharp: Please add node-gyp to your dependencies`，要么安装构建工具（macOS：Xcode CLT + `npm install -g node-gyp`），要么使用上面的 `SHARP_IGNORE_GLOBAL_LIBVIPS=1` 变通方法来跳过原生构建。
|
||||
|
||||
或使用 pnpm：
|
||||
|
||||
```bash
|
||||
pnpm add -g openclaw@latest
|
||||
pnpm approve-builds -g # 批准 openclaw、node-llama-cpp、sharp 等
|
||||
pnpm add -g openclaw@latest # 重新运行以执行 postinstall 脚本
|
||||
```
|
||||
|
||||
pnpm 需要显式批准带有构建脚本的包。在首次安装显示"Ignored build scripts"警告后，运行 `pnpm approve-builds -g` 并选择列出的包，然后重新运行安装以执行 postinstall 脚本。
|
||||
|
||||
然后：
|
||||
|
||||
```bash
|
||||
openclaw onboard --install-daemon
|
||||
```
|
||||
|
||||
### 3）从源代码（贡献者/开发）
|
||||
|
||||
```bash
|
||||
git clone https://github.com/openclaw/openclaw.git
|
||||
cd openclaw
|
||||
pnpm install
|
||||
pnpm ui:build # 首次运行时自动安装 UI 依赖
|
||||
pnpm build
|
||||
openclaw onboard --install-daemon
|
||||
```
|
||||
|
||||
提示：如果你还没有全局安装，请通过 `pnpm openclaw ...` 运行仓库命令。
|
||||
|
||||
### 4）其他安装选项
|
||||
|
||||
- Docker：[Docker](/install/docker)
|
||||
- Nix：[Nix](/install/nix)
|
||||
- Ansible：[Ansible](/install/ansible)
|
||||
- Bun（仅 CLI）：[Bun](/install/bun)
|
||||
|
||||
## 安装后
|
||||
|
||||
- 运行新手引导：`openclaw onboard --install-daemon`
|
||||
- 快速检查：`openclaw doctor`
|
||||
- 检查 Gateway 网关健康状态：`openclaw status` + `openclaw health`
|
||||
- 打开仪表板：`openclaw dashboard`
|
||||
|
||||
## 安装方式：npm vs git（安装器）
|
||||
|
||||
安装器支持两种方式：
|
||||
|
||||
- `npm`（默认）：`npm install -g openclaw@latest`
|
||||
- `git`：从 GitHub 克隆/构建并从源代码 checkout 运行
|
||||
|
||||
### CLI 标志
|
||||
|
||||
```bash
|
||||
# 显式 npm
|
||||
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm
|
||||
|
||||
# 从 GitHub 安装（源代码 checkout）
|
||||
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git
|
||||
```
|
||||
|
||||
常用标志：
|
||||
|
||||
- `--install-method npm|git`
|
||||
- `--git-dir <path>`（默认：`~/openclaw`）
|
||||
- `--no-git-update`（使用现有 checkout 时跳过 `git pull`）
|
||||
- `--no-prompt`（禁用提示；CI/自动化中必需）
|
||||
- `--dry-run`（打印将要执行的操作；不做任何更改）
|
||||
- `--no-onboard`（跳过新手引导）
|
||||
|
||||
### 环境变量
|
||||
|
||||
等效的环境变量（对自动化有用）：
|
||||
|
||||
- `OPENCLAW_INSTALL_METHOD=git|npm`
|
||||
- `OPENCLAW_GIT_DIR=...`
|
||||
- `OPENCLAW_GIT_UPDATE=0|1`
|
||||
- `OPENCLAW_NO_PROMPT=1`
|
||||
- `OPENCLAW_DRY_RUN=1`
|
||||
- `OPENCLAW_NO_ONBOARD=1`
|
||||
- `SHARP_IGNORE_GLOBAL_LIBVIPS=0|1`（默认：`1`；避免 `sharp` 针对系统 libvips 构建）
|
||||
|
||||
## 故障排除：找不到 `openclaw`（PATH）
|
||||
|
||||
快速诊断：
|
||||
|
||||
```bash
|
||||
node -v
|
||||
npm -v
|
||||
npm prefix -g
|
||||
echo "$PATH"
|
||||
```
|
||||
|
||||
如果 `$(npm prefix -g)/bin`（macOS/Linux）或 `$(npm prefix -g)`（Windows）**不**在 `echo "$PATH"` 的输出中，你的 shell 无法找到全局 npm 二进制文件（包括 `openclaw`）。
|
||||
|
||||
修复：将其添加到你的 shell 启动文件（zsh：`~/.zshrc`，bash：`~/.bashrc`）：
|
||||
|
||||
```bash
|
||||
# macOS / Linux
|
||||
export PATH="$(npm prefix -g)/bin:$PATH"
|
||||
```
|
||||
|
||||
在 Windows 上，将 `npm prefix -g` 的输出添加到你的 PATH。
|
||||
|
||||
然后打开新终端（或在 zsh 中执行 `rehash` / 在 bash 中执行 `hash -r`）。
|
||||
|
||||
## 更新/卸载
|
||||
|
||||
- 更新：[更新](/install/updating)
|
||||
- 迁移到新机器：[迁移](/install/migrating)
|
||||
- 卸载：[卸载](/install/uninstall)
|
||||
128
content/install/installer.md
Normal file
128
content/install/installer.md
Normal file
@@ -0,0 +1,128 @@
|
||||
---
|
||||
read_when:
|
||||
- 你想了解 `openclaw.ai/install.sh` 的工作机制
|
||||
- 你想自动化安装（CI / 无头环境）
|
||||
- 你想从 GitHub 检出安装
|
||||
summary: 安装器脚本的工作原理（install.sh + install-cli.sh）、参数和自动化
|
||||
title: 安装器内部机制
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T21:07:55Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: 9e0a19ecb5da0a395030e1ccf0d4bedf16b83946b3432c5399d448fe5d298391
|
||||
source_path: install/installer.md
|
||||
workflow: 14
|
||||
---
|
||||
|
||||
# 安装器内部机制
|
||||
|
||||
OpenClaw 提供两个安装器脚本（托管在 `openclaw.ai`）：
|
||||
|
||||
- `https://openclaw.ai/install.sh` — "推荐"安装器（默认全局 npm 安装；也可从 GitHub 检出安装）
|
||||
- `https://openclaw.ai/install-cli.sh` — 无需 root 权限的 CLI 安装器（安装到带有独立 Node 的前缀目录）
|
||||
- `https://openclaw.ai/install.ps1` — Windows PowerShell 安装器（默认 npm；可选 git 安装）
|
||||
|
||||
查看当前参数/行为，运行：
|
||||
|
||||
```bash
|
||||
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --help
|
||||
```
|
||||
|
||||
Windows (PowerShell) 帮助：
|
||||
|
||||
```powershell
|
||||
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -?
|
||||
```
|
||||
|
||||
如果安装器完成但在新终端中找不到 `openclaw`，通常是 Node/npm PATH 问题。参见：[安装](/install#nodejs--npm-path-sanity)。
|
||||
|
||||
## install.sh（推荐）
|
||||
|
||||
功能概述：
|
||||
|
||||
- 检测操作系统（macOS / Linux / WSL）。
|
||||
- 确保 Node.js **22+**（macOS 通过 Homebrew；Linux 通过 NodeSource）。
|
||||
- 选择安装方式：
|
||||
- `npm`（默认）：`npm install -g openclaw@latest`
|
||||
- `git`：克隆/构建源码检出并安装包装脚本
|
||||
- 在 Linux 上：必要时将 npm 前缀切换到 `~/.npm-global`，以避免全局 npm 权限错误。
|
||||
- 如果是升级现有安装：运行 `openclaw doctor --non-interactive`（尽力执行）。
|
||||
- 对于 git 安装：安装/更新后运行 `openclaw doctor --non-interactive`（尽力执行）。
|
||||
- 通过默认设置 `SHARP_IGNORE_GLOBAL_LIBVIPS=1` 来缓解 `sharp` 原生安装问题（避免使用系统 libvips 编译）。
|
||||
|
||||
如果你*希望* `sharp` 链接到全局安装的 libvips（或你正在调试），请设置：
|
||||
|
||||
```bash
|
||||
SHARP_IGNORE_GLOBAL_LIBVIPS=0 curl -fsSL https://openclaw.ai/install.sh | bash
|
||||
```
|
||||
|
||||
### 可发现性 / "git 安装"提示
|
||||
|
||||
如果你在**已有的 OpenClaw 源码检出目录中**运行安装器（通过 `package.json` + `pnpm-workspace.yaml` 检测），它会提示：
|
||||
|
||||
- 更新并使用此检出（`git`）
|
||||
- 或迁移到全局 npm 安装（`npm`）
|
||||
|
||||
在非交互式上下文中（无 TTY / `--no-prompt`），你必须传入 `--install-method git|npm`（或设置 `OPENCLAW_INSTALL_METHOD`），否则脚本将以退出码 `2` 退出。
|
||||
|
||||
### 为什么需要 Git
|
||||
|
||||
`--install-method git` 路径（克隆 / 拉取）需要 Git。
|
||||
|
||||
对于 `npm` 安装，Git *通常*不是必需的，但某些环境仍然需要它（例如通过 git URL 获取软件包或依赖时）。安装器目前会确保 Git 存在，以避免在全新发行版上出现 `spawn git ENOENT` 错误。
|
||||
|
||||
### 为什么在全新 Linux 上 npm 会报 `EACCES`
|
||||
|
||||
在某些 Linux 设置中（尤其是通过系统包管理器或 NodeSource 安装 Node 后），npm 的全局前缀指向 root 拥有的位置。此时 `npm install -g ...` 会报 `EACCES` / `mkdir` 权限错误。
|
||||
|
||||
`install.sh` 通过将前缀切换到以下位置来缓解此问题：
|
||||
|
||||
- `~/.npm-global`（并在存在时将其添加到 `~/.bashrc` / `~/.zshrc` 的 `PATH` 中）
|
||||
|
||||
## install-cli.sh（无需 root 权限的 CLI 安装器）
|
||||
|
||||
此脚本将 `openclaw` 安装到前缀目录（默认：`~/.openclaw`），同时在该前缀下安装专用的 Node 运行时，因此可以在不想改动系统 Node/npm 的机器上使用。
|
||||
|
||||
帮助：
|
||||
|
||||
```bash
|
||||
curl -fsSL https://openclaw.ai/install-cli.sh | bash -s -- --help
|
||||
```
|
||||
|
||||
## install.ps1（Windows PowerShell）
|
||||
|
||||
功能概述：
|
||||
|
||||
- 确保 Node.js **22+**（winget/Chocolatey/Scoop 或手动安装）。
|
||||
- 选择安装方式：
|
||||
- `npm`（默认）：`npm install -g openclaw@latest`
|
||||
- `git`：克隆/构建源码检出并安装包装脚本
|
||||
- 在升级和 git 安装时运行 `openclaw doctor --non-interactive`（尽力执行）。
|
||||
|
||||
示例：
|
||||
|
||||
```powershell
|
||||
iwr -useb https://openclaw.ai/install.ps1 | iex
|
||||
```
|
||||
|
||||
```powershell
|
||||
iwr -useb https://openclaw.ai/install.ps1 | iex -InstallMethod git
|
||||
```
|
||||
|
||||
```powershell
|
||||
iwr -useb https://openclaw.ai/install.ps1 | iex -InstallMethod git -GitDir "C:\\openclaw"
|
||||
```
|
||||
|
||||
环境变量：
|
||||
|
||||
- `OPENCLAW_INSTALL_METHOD=git|npm`
|
||||
- `OPENCLAW_GIT_DIR=...`
|
||||
|
||||
Git 要求：
|
||||
|
||||
如果你选择 `-InstallMethod git` 但未安装 Git，安装器会打印 Git for Windows 的链接（`https://git-scm.com/download/win`）并退出。
|
||||
|
||||
常见 Windows 问题：
|
||||
|
||||
- **npm error spawn git / ENOENT**：安装 Git for Windows 并重新打开 PowerShell，然后重新运行安装器。
|
||||
- **"openclaw" 不是可识别的命令**：你的 npm 全局 bin 文件夹不在 PATH 中。大多数系统使用 `%AppData%\\npm`。你也可以运行 `npm config get prefix` 并将 `\\bin` 添加到 PATH，然后重新打开 PowerShell。
|
||||
288
content/install/macos-vm.md
Normal file
288
content/install/macos-vm.md
Normal file
@@ -0,0 +1,288 @@
|
||||
---
|
||||
read_when:
|
||||
- 你想让 OpenClaw 与你的主 macOS 环境隔离
|
||||
- 你想在沙箱中集成 iMessage（BlueBubbles）
|
||||
- 你想要一个可重置、可克隆的 macOS 环境
|
||||
- 你想比较本地与托管 macOS VM 选项
|
||||
summary: 在沙箱隔离的 macOS VM（本地或托管）中运行 OpenClaw，当你需要隔离或 iMessage 时
|
||||
title: macOS 虚拟机
|
||||
x-i18n:
|
||||
generated_at: "2026-02-03T07:53:09Z"
|
||||
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 VM。
|
||||
|
||||
## macOS VM 选项
|
||||
|
||||
### 在你的 Apple Silicon Mac 上运行本地 VM（Lume）
|
||||
|
||||
使用 [Lume](https://cua.ai/docs/lume) 在你现有的 Apple Silicon Mac 上的沙箱 macOS VM 中运行 OpenClaw。
|
||||
|
||||
这为你提供：
|
||||
|
||||
- 隔离的完整 macOS 环境（你的主机保持干净）
|
||||
- 通过 BlueBubbles 支持 iMessage（在 Linux/Windows 上不可能）
|
||||
- 通过克隆 VM 即时重置
|
||||
- 无需额外硬件或云成本
|
||||
|
||||
### 托管 Mac 提供商（云）
|
||||
|
||||
如果你想要云端的 macOS，托管 Mac 提供商也可以：
|
||||
|
||||
- [MacStadium](https://www.macstadium.com/)（托管 Mac）
|
||||
- 其他托管 Mac 供应商也可以；按照他们的 VM + SSH 文档操作
|
||||
|
||||
一旦你有了 macOS VM 的 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 或更高版本
|
||||
- 每个 VM 约 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 VM
|
||||
|
||||
```bash
|
||||
lume create openclaw --os macos --ipsw latest
|
||||
```
|
||||
|
||||
这会下载 macOS 并创建 VM。VNC 窗口会自动打开。
|
||||
|
||||
注意：下载可能需要一段时间，取决于你的网络连接。
|
||||
|
||||
---
|
||||
|
||||
## 3) 完成设置助手
|
||||
|
||||
在 VNC 窗口中：
|
||||
|
||||
1. 选择语言和地区
|
||||
2. 跳过 Apple ID（或者如果你以后想要 iMessage 就登录）
|
||||
3. 创建用户账户（记住用户名和密码）
|
||||
4. 跳过所有可选功能
|
||||
|
||||
设置完成后，启用 SSH：
|
||||
|
||||
1. 打开系统设置 → 通用 → 共享
|
||||
2. 启用"远程登录"
|
||||
|
||||
---
|
||||
|
||||
## 4) 获取 VM 的 IP 地址
|
||||
|
||||
```bash
|
||||
lume get openclaw
|
||||
```
|
||||
|
||||
查找 IP 地址（通常是 `192.168.64.x`）。
|
||||
|
||||
---
|
||||
|
||||
## 5) SSH 进入 VM
|
||||
|
||||
```bash
|
||||
ssh youruser@192.168.64.X
|
||||
```
|
||||
|
||||
将 `youruser` 替换为你创建的账户，IP 替换为你 VM 的 IP。
|
||||
|
||||
---
|
||||
|
||||
## 6) 安装 OpenClaw
|
||||
|
||||
在 VM 内：
|
||||
|
||||
```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) 无头运行 VM
|
||||
|
||||
停止 VM 并在无显示器模式下重启：
|
||||
|
||||
```bash
|
||||
lume stop openclaw
|
||||
lume run openclaw --no-display
|
||||
```
|
||||
|
||||
VM 在后台运行。OpenClaw 的守护进程保持 Gateway 网关运行。
|
||||
|
||||
检查状态：
|
||||
|
||||
```bash
|
||||
ssh youruser@192.168.64.X "openclaw status"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 额外：iMessage 集成
|
||||
|
||||
这是在 macOS 上运行的杀手级功能。使用 [BlueBubbles](https://bluebubbles.app) 将 iMessage 添加到 OpenClaw。
|
||||
|
||||
在 VM 内：
|
||||
|
||||
1. 从 bluebubbles.app 下载 BlueBubbles
|
||||
2. 用你的 Apple ID 登录
|
||||
3. 启用 Web API 并设置密码
|
||||
4. 将 BlueBubbles webhooks 指向你的 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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 24/7 运行
|
||||
|
||||
通过以下方式保持 VM 运行：
|
||||
|
||||
- 保持你的 Mac 插电
|
||||
- 在系统设置 → 节能中禁用睡眠
|
||||
- 如需要使用 `caffeinate`
|
||||
|
||||
对于真正的永久在线，考虑专用 Mac mini 或小型 VPS。参见 [VPS 托管](/vps)。
|
||||
|
||||
---
|
||||
|
||||
## 故障排除
|
||||
|
||||
| 问题 | 解决方案 |
|
||||
| ----------------------- | ---------------------------------------------------------------- |
|
||||
| 无法 SSH 进入 VM | 检查 VM 的系统设置中是否启用了"远程登录" |
|
||||
| VM IP 未显示 | 等待 VM 完全启动，再次运行 `lume get openclaw` |
|
||||
| 找不到 Lume 命令 | 将 `~/.local/bin` 添加到你的 PATH |
|
||||
| WhatsApp 二维码扫描失败 | 确保运行 `openclaw channels login` 时你是登录到 VM（而不是主机） |
|
||||
|
||||
---
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [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)
|
||||
- [无人值守 VM 设置](https://cua.ai/docs/lume/guide/fundamentals/unattended-setup)（高级）
|
||||
- [Docker 沙箱隔离](/install/docker)（替代隔离方案）
|
||||
199
content/install/migrating.md
Normal file
199
content/install/migrating.md
Normal file
@@ -0,0 +1,199 @@
|
||||
---
|
||||
read_when:
|
||||
- 你正在将 OpenClaw 迁移到新的笔记本电脑/服务器
|
||||
- 你想保留会话、认证和渠道登录（WhatsApp 等）
|
||||
summary: 将 OpenClaw 安装从一台机器迁移到另一台
|
||||
title: 迁移指南
|
||||
x-i18n:
|
||||
generated_at: "2026-02-03T07:49:55Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: 604d862c4bf86e7924d09028db8cc2514ca6f1d64ebe8bb7d1e2dde57ef70caa
|
||||
source_path: install/migrating.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 将 OpenClaw 迁移到新机器
|
||||
|
||||
本指南将 OpenClaw Gateway 网关从一台机器迁移到另一台，**无需重新进行新手引导**。
|
||||
|
||||
迁移在概念上很简单：
|
||||
|
||||
- 复制**状态目录**（`$OPENCLAW_STATE_DIR`，默认：`~/.openclaw/`）— 这包括配置、认证、会话和渠道状态。
|
||||
- 复制你的**工作区**（默认 `~/.openclaw/workspace/`）— 这包括你的智能体文件（记忆、提示等）。
|
||||
|
||||
但在**配置文件**、**权限**和**部分复制**方面有常见的陷阱。
|
||||
|
||||
## 开始之前（你要迁移什么）
|
||||
|
||||
### 1）确定你的状态目录
|
||||
|
||||
大多数安装使用默认值：
|
||||
|
||||
- **状态目录：** `~/.openclaw/`
|
||||
|
||||
但如果你使用以下方式，可能会不同：
|
||||
|
||||
- `--profile <name>`（通常变成 `~/.openclaw-<profile>/`）
|
||||
- `OPENCLAW_STATE_DIR=/some/path`
|
||||
|
||||
如果你不确定，在**旧**机器上运行：
|
||||
|
||||
```bash
|
||||
openclaw status
|
||||
```
|
||||
|
||||
在输出中查找 `OPENCLAW_STATE_DIR` / profile 的提及。如果你运行多个 Gateway 网关，对每个配置文件重复此操作。
|
||||
|
||||
### 2）确定你的工作区
|
||||
|
||||
常见默认值：
|
||||
|
||||
- `~/.openclaw/workspace/`（推荐的工作区）
|
||||
- 你创建的自定义文件夹
|
||||
|
||||
你的工作区是 `MEMORY.md`、`USER.md` 和 `memory/*.md` 等文件所在的位置。
|
||||
|
||||
### 3）了解你将保留什么
|
||||
|
||||
如果你复制**两者**——状态目录和工作区，你将保留：
|
||||
|
||||
- Gateway 网关配置（`openclaw.json`）
|
||||
- 认证配置文件 / API 密钥 / OAuth 令牌
|
||||
- 会话历史 + 智能体状态
|
||||
- 渠道状态（例如 WhatsApp 登录/会话）
|
||||
- 你的工作区文件（记忆、Skills 笔记等）
|
||||
|
||||
如果你**只**复制工作区（例如通过 Git），你**不会**保留：
|
||||
|
||||
- 会话
|
||||
- 凭证
|
||||
- 渠道登录
|
||||
|
||||
这些存储在 `$OPENCLAW_STATE_DIR` 下。
|
||||
|
||||
## 迁移步骤（推荐）
|
||||
|
||||
### 步骤 0 — 备份（旧机器）
|
||||
|
||||
在**旧**机器上，首先停止 Gateway 网关，这样文件不会在复制过程中发生变化：
|
||||
|
||||
```bash
|
||||
openclaw gateway stop
|
||||
```
|
||||
|
||||
（可选但推荐）归档状态目录和工作区：
|
||||
|
||||
```bash
|
||||
# 如果你使用配置文件或自定义位置，请调整路径
|
||||
cd ~
|
||||
tar -czf openclaw-state.tgz .openclaw
|
||||
|
||||
tar -czf openclaw-workspace.tgz .openclaw/workspace
|
||||
```
|
||||
|
||||
如果你有多个配置文件/状态目录（例如 `~/.openclaw-main`、`~/.openclaw-work`），分别归档每个。
|
||||
|
||||
### 步骤 1 — 在新机器上安装 OpenClaw
|
||||
|
||||
在**新**机器上，安装 CLI（如果需要还有 Node）：
|
||||
|
||||
- 参见：[安装](/install)
|
||||
|
||||
在这个阶段，如果新手引导创建了一个新的 `~/.openclaw/` 也没关系 — 你将在下一步覆盖它。
|
||||
|
||||
### 步骤 2 — 将状态目录 + 工作区复制到新机器
|
||||
|
||||
复制**两者**：
|
||||
|
||||
- `$OPENCLAW_STATE_DIR`（默认 `~/.openclaw/`）
|
||||
- 你的工作区（默认 `~/.openclaw/workspace/`）
|
||||
|
||||
常见方法：
|
||||
|
||||
- `scp` 压缩包并解压
|
||||
- 通过 SSH 使用 `rsync -a`
|
||||
- 外部驱动器
|
||||
|
||||
复制后，确保：
|
||||
|
||||
- 包含了隐藏目录（例如 `.openclaw/`）
|
||||
- 文件所有权对于运行 Gateway 网关的用户是正确的
|
||||
|
||||
### 步骤 3 — 运行 Doctor（迁移 + 服务修复）
|
||||
|
||||
在**新**机器上：
|
||||
|
||||
```bash
|
||||
openclaw doctor
|
||||
```
|
||||
|
||||
Doctor 是"安全可靠"的命令。它修复服务、应用配置迁移，并警告不匹配问题。
|
||||
|
||||
然后：
|
||||
|
||||
```bash
|
||||
openclaw gateway restart
|
||||
openclaw status
|
||||
```
|
||||
|
||||
## 常见陷阱（以及如何避免）
|
||||
|
||||
### 陷阱：配置文件/状态目录不匹配
|
||||
|
||||
如果你在旧 Gateway 网关上使用了配置文件（或 `OPENCLAW_STATE_DIR`），而新 Gateway 网关使用了不同的配置，你会看到如下症状：
|
||||
|
||||
- 配置更改不生效
|
||||
- 渠道丢失/已登出
|
||||
- 会话历史为空
|
||||
|
||||
修复：使用你迁移的**相同**配置文件/状态目录运行 Gateway 网关/服务，然后重新运行：
|
||||
|
||||
```bash
|
||||
openclaw doctor
|
||||
```
|
||||
|
||||
### 陷阱：只复制 `openclaw.json`
|
||||
|
||||
`openclaw.json` 是不够的。许多提供商在以下位置存储状态：
|
||||
|
||||
- `$OPENCLAW_STATE_DIR/credentials/`
|
||||
- `$OPENCLAW_STATE_DIR/agents/<agentId>/...`
|
||||
|
||||
始终迁移整个 `$OPENCLAW_STATE_DIR` 文件夹。
|
||||
|
||||
### 陷阱：权限/所有权
|
||||
|
||||
如果你以 root 身份复制或更改了用户，Gateway 网关可能无法读取凭证/会话。
|
||||
|
||||
修复：确保状态目录 + 工作区由运行 Gateway 网关的用户拥有。
|
||||
|
||||
### 陷阱：在远程/本地模式之间迁移
|
||||
|
||||
- 如果你的 UI（WebUI/TUI）指向**远程** Gateway 网关，远程主机拥有会话存储 + 工作区。
|
||||
- 迁移你的笔记本电脑不会移动远程 Gateway 网关的状态。
|
||||
|
||||
如果你处于远程模式，请迁移 **Gateway 网关主机**。
|
||||
|
||||
### 陷阱：备份中的密钥
|
||||
|
||||
`$OPENCLAW_STATE_DIR` 包含密钥（API 密钥、OAuth 令牌、WhatsApp 凭证）。将备份视为生产密钥：
|
||||
|
||||
- 加密存储
|
||||
- 避免通过不安全的渠道共享
|
||||
- 如果怀疑泄露，轮换密钥
|
||||
|
||||
## 验证检查清单
|
||||
|
||||
在新机器上，确认：
|
||||
|
||||
- `openclaw status` 显示 Gateway 网关正在运行
|
||||
- 你的渠道仍然连接（例如 WhatsApp 不需要重新配对）
|
||||
- 仪表板打开并显示现有会话
|
||||
- 你的工作区文件（记忆、配置）存在
|
||||
|
||||
## 相关内容
|
||||
|
||||
- [Doctor](/gateway/doctor)
|
||||
- [Gateway 网关故障排除](/gateway/troubleshooting)
|
||||
- [OpenClaw 在哪里存储数据？](/help/faq#where-does-openclaw-store-its-data)
|
||||
99
content/install/nix.md
Normal file
99
content/install/nix.md
Normal file
@@ -0,0 +1,99 @@
|
||||
---
|
||||
read_when:
|
||||
- 你想要可复现、可回滚的安装
|
||||
- 你已经在使用 Nix/NixOS/Home Manager
|
||||
- 你想要所有内容都固定并以声明式管理
|
||||
summary: 使用 Nix 声明式安装 OpenClaw
|
||||
title: Nix
|
||||
x-i18n:
|
||||
generated_at: "2026-02-03T07:49:51Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: f1452194cfdd74613b5b3ab90b0d506eaea2d16b147497987710d6ad658312ba
|
||||
source_path: install/nix.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Nix 安装
|
||||
|
||||
使用 Nix 运行 OpenClaw 的推荐方式是通过 **[nix-openclaw](https://github.com/openclaw/nix-openclaw)** — 一个开箱即用的 Home Manager 模块。
|
||||
|
||||
## 快速开始
|
||||
|
||||
将此粘贴给你的 AI 智能体（Claude、Cursor 等）：
|
||||
|
||||
```text
|
||||
I want to set up nix-openclaw on my Mac.
|
||||
Repository: github:openclaw/nix-openclaw
|
||||
|
||||
What I need you to do:
|
||||
1. Check if Determinate Nix is installed (if not, install it)
|
||||
2. Create a local flake at ~/code/openclaw-local using templates/agent-first/flake.nix
|
||||
3. Help me create a Telegram bot (@BotFather) and get my chat ID (@userinfobot)
|
||||
4. Set up secrets (bot token, Anthropic key) - plain files at ~/.secrets/ is fine
|
||||
5. Fill in the template placeholders and run home-manager switch
|
||||
6. Verify: launchd running, bot responds to messages
|
||||
|
||||
Reference the nix-openclaw README for module options.
|
||||
```
|
||||
|
||||
> **📦 完整指南：[github.com/openclaw/nix-openclaw](https://github.com/openclaw/nix-openclaw)**
|
||||
>
|
||||
> nix-openclaw 仓库是 Nix 安装的权威来源。本页只是一个快速概述。
|
||||
|
||||
## 你将获得
|
||||
|
||||
- Gateway 网关 + macOS 应用 + 工具（whisper、spotify、cameras）— 全部固定版本
|
||||
- 重启后仍能运行的 Launchd 服务
|
||||
- 带有声明式配置的插件系统
|
||||
- 即时回滚：`home-manager switch --rollback`
|
||||
|
||||
---
|
||||
|
||||
## Nix 模式运行时行为
|
||||
|
||||
当设置 `OPENCLAW_NIX_MODE=1` 时（nix-openclaw 会自动设置）：
|
||||
|
||||
OpenClaw 支持 **Nix 模式**，使配置确定性并禁用自动安装流程。
|
||||
通过导出以下环境变量启用：
|
||||
|
||||
```bash
|
||||
OPENCLAW_NIX_MODE=1
|
||||
```
|
||||
|
||||
在 macOS 上，GUI 应用不会自动继承 shell 环境变量。你也可以通过 defaults 启用 Nix 模式：
|
||||
|
||||
```bash
|
||||
defaults write bot.molt.mac openclaw.nixMode -bool true
|
||||
```
|
||||
|
||||
### 配置 + 状态路径
|
||||
|
||||
OpenClaw 从 `OPENCLAW_CONFIG_PATH` 读取 JSON5 配置，并将可变数据存储在 `OPENCLAW_STATE_DIR` 中。
|
||||
|
||||
- `OPENCLAW_STATE_DIR`（默认：`~/.openclaw`）
|
||||
- `OPENCLAW_CONFIG_PATH`（默认：`$OPENCLAW_STATE_DIR/openclaw.json`）
|
||||
|
||||
在 Nix 下运行时，将这些显式设置为 Nix 管理的位置，以便运行时状态和配置不会进入不可变存储。
|
||||
|
||||
### Nix 模式下的运行时行为
|
||||
|
||||
- 自动安装和自我修改流程被禁用
|
||||
- 缺失的依赖会显示 Nix 特定的修复消息
|
||||
- 存在时 UI 会显示只读 Nix 模式横幅
|
||||
|
||||
## 打包注意事项（macOS）
|
||||
|
||||
macOS 打包流程期望在以下位置有一个稳定的 Info.plist 模板：
|
||||
|
||||
```
|
||||
apps/macos/Sources/OpenClaw/Resources/Info.plist
|
||||
```
|
||||
|
||||
[`scripts/package-mac-app.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/package-mac-app.sh) 将此模板复制到应用包中并修补动态字段（bundle ID、版本/构建号、Git SHA、Sparkle 密钥）。这使 plist 对于 SwiftPM 打包和 Nix 构建保持确定性（它们不依赖完整的 Xcode 工具链）。
|
||||
|
||||
## 相关内容
|
||||
|
||||
- [nix-openclaw](https://github.com/openclaw/nix-openclaw) — 完整设置指南
|
||||
- [向导](/start/wizard) — 非 Nix CLI 设置
|
||||
- [Docker](/install/docker) — 容器化设置
|
||||
8
content/install/node.md
Normal file
8
content/install/node.md
Normal file
@@ -0,0 +1,8 @@
|
||||
---
|
||||
summary: Node.js 安装与配置（OpenClaw 版本要求、安装方式与 PATH 排错）
|
||||
title: Node.js
|
||||
---
|
||||
|
||||
# Node.js
|
||||
|
||||
该页面是英文文档的中文占位版本，完整内容请先参考英文版：[Node.js](/install/node)。
|
||||
60
content/install/northflank.mdx
Normal file
60
content/install/northflank.mdx
Normal file
@@ -0,0 +1,60 @@
|
||||
---
|
||||
title: 在 Northflank 上部署
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T21:19:03Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: ad0be8dda41c51d0b6424259316db1b22be5216434f5879f21a5e8c60e0a2ee0
|
||||
source_path: northflank.mdx
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
通过一键模板在 Northflank 上部署 OpenClaw，然后在浏览器中完成设置。
|
||||
这是最简单的"无需在服务器上使用终端"的方式：Northflank 为你运行 Gateway网关，
|
||||
你通过 `/setup` 网页向导配置一切。
|
||||
|
||||
## 如何开始
|
||||
|
||||
1. 点击 [Deploy OpenClaw](https://northflank.com/stacks/deploy-openclaw) 打开模板。
|
||||
2. 如果你还没有账户，请创建一个 [Northflank 账户](https://app.northflank.com/signup)。
|
||||
3. 点击 **Deploy OpenClaw now**。
|
||||
4. 设置必需的环境变量：`SETUP_PASSWORD`。
|
||||
5. 点击 **Deploy stack** 构建并运行 OpenClaw 模板。
|
||||
6. 等待部署完成，然后点击 **View resources**。
|
||||
7. 打开 OpenClaw 服务。
|
||||
8. 打开公开的 OpenClaw URL，在 `/setup` 完成设置。
|
||||
9. 在 `/openclaw` 打开控制面板 UI。
|
||||
|
||||
## 你将获得
|
||||
|
||||
- 托管的 OpenClaw Gateway网关 + 控制面板 UI
|
||||
- `/setup` 处的网页设置向导（无需终端命令）
|
||||
- 通过 Northflank Volume（`/data`）实现持久化存储，配置/凭据/工作区在重新部署后不会丢失
|
||||
|
||||
## 设置流程
|
||||
|
||||
1. 访问 `https://<your-northflank-domain>/setup` 并输入你的 `SETUP_PASSWORD`。
|
||||
2. 选择模型/认证提供商并粘贴你的密钥。
|
||||
3. （可选）添加 Telegram/Discord/Slack 令牌。
|
||||
4. 点击 **Run setup**。
|
||||
5. 在 `https://<your-northflank-domain>/openclaw` 打开控制面板 UI。
|
||||
|
||||
如果 Telegram 私信设置为配对模式，设置向导可以审批配对码。
|
||||
|
||||
## 获取聊天令牌
|
||||
|
||||
### Telegram 机器人令牌
|
||||
|
||||
1. 在 Telegram 中给 `@BotFather` 发消息
|
||||
2. 运行 `/newbot`
|
||||
3. 复制令牌（格式如 `123456789:AA...`）
|
||||
4. 将其粘贴到 `/setup` 中
|
||||
|
||||
### Discord 机器人令牌
|
||||
|
||||
1. 前往 https://discord.com/developers/applications
|
||||
2. **New Application** → 选择一个名称
|
||||
3. **Bot** → **Add Bot**
|
||||
4. 在 Bot → Privileged Gateway Intents 下**启用 MESSAGE CONTENT INTENT**（必需，否则机器人启动时会崩溃）
|
||||
5. 复制 **Bot Token** 并粘贴到 `/setup` 中
|
||||
6. 邀请机器人加入你的服务器（OAuth2 URL Generator；权限范围：`bot`、`applications.commands`）
|
||||
109
content/install/podman.md
Normal file
109
content/install/podman.md
Normal file
@@ -0,0 +1,109 @@
|
||||
---
|
||||
summary: "Run OpenClaw in a rootless Podman container"
|
||||
read_when:
|
||||
- You want a containerized gateway with Podman instead of Docker
|
||||
title: "Podman"
|
||||
---
|
||||
|
||||
# Podman
|
||||
|
||||
Run the OpenClaw gateway in a **rootless** Podman container. Uses the same image as Docker (build from the repo [Dockerfile](https://github.com/openclaw/openclaw/blob/main/Dockerfile)).
|
||||
|
||||
## Requirements
|
||||
|
||||
- Podman (rootless)
|
||||
- Sudo for one-time setup (create user, build image)
|
||||
|
||||
## Quick start
|
||||
|
||||
**1. One-time setup** (from repo root; creates user, builds image, installs launch script):
|
||||
|
||||
```bash
|
||||
./setup-podman.sh
|
||||
```
|
||||
|
||||
This also creates a minimal `~openclaw/.openclaw/openclaw.json` (sets `gateway.mode="local"`) so the gateway can start without running the wizard.
|
||||
|
||||
By default the container is **not** installed as a systemd service, you start it manually (see below). For a production-style setup with auto-start and restarts, install it as a systemd Quadlet user service instead:
|
||||
|
||||
```bash
|
||||
./setup-podman.sh --quadlet
|
||||
```
|
||||
|
||||
(Or set `OPENCLAW_PODMAN_QUADLET=1`; use `--container` to install only the container and launch script.)
|
||||
|
||||
**2. Start gateway** (manual, for quick smoke testing):
|
||||
|
||||
```bash
|
||||
./scripts/run-openclaw-podman.sh launch
|
||||
```
|
||||
|
||||
**3. Onboarding wizard** (e.g. to add channels or providers):
|
||||
|
||||
```bash
|
||||
./scripts/run-openclaw-podman.sh launch setup
|
||||
```
|
||||
|
||||
Then open `http://127.0.0.1:18789/` and use the token from `~openclaw/.openclaw/.env` (or the value printed by setup).
|
||||
|
||||
## Systemd (Quadlet, optional)
|
||||
|
||||
If you ran `./setup-podman.sh --quadlet` (or `OPENCLAW_PODMAN_QUADLET=1`), a [Podman Quadlet](https://docs.podman.io/en/latest/markdown/podman-systemd.unit.5.html) unit is installed so the gateway runs as a systemd user service for the openclaw user. The service is enabled and started at the end of setup.
|
||||
|
||||
- **Start:** `sudo systemctl --machine openclaw@ --user start openclaw.service`
|
||||
- **Stop:** `sudo systemctl --machine openclaw@ --user stop openclaw.service`
|
||||
- **Status:** `sudo systemctl --machine openclaw@ --user status openclaw.service`
|
||||
- **Logs:** `sudo journalctl --machine openclaw@ --user -u openclaw.service -f`
|
||||
|
||||
The quadlet file lives at `~openclaw/.config/containers/systemd/openclaw.container`. To change ports or env, edit that file (or the `.env` it sources), then `sudo systemctl --machine openclaw@ --user daemon-reload` and restart the service. On boot, the service starts automatically if lingering is enabled for openclaw (setup does this when loginctl is available).
|
||||
|
||||
To add quadlet **after** an initial setup that did not use it, re-run: `./setup-podman.sh --quadlet`.
|
||||
|
||||
## The openclaw user (non-login)
|
||||
|
||||
`setup-podman.sh` creates a dedicated system user `openclaw`:
|
||||
|
||||
- **Shell:** `nologin` — no interactive login; reduces attack surface.
|
||||
- **Home:** e.g. `/home/openclaw` — holds `~/.openclaw` (config, workspace) and the launch script `run-openclaw-podman.sh`.
|
||||
- **Rootless Podman:** The user must have a **subuid** and **subgid** range. Many distros assign these automatically when the user is created. If setup prints a warning, add lines to `/etc/subuid` and `/etc/subgid`:
|
||||
|
||||
```text
|
||||
openclaw:100000:65536
|
||||
```
|
||||
|
||||
Then start the gateway as that user (e.g. from cron or systemd):
|
||||
|
||||
```bash
|
||||
sudo -u openclaw /home/openclaw/run-openclaw-podman.sh
|
||||
sudo -u openclaw /home/openclaw/run-openclaw-podman.sh setup
|
||||
```
|
||||
|
||||
- **Config:** Only `openclaw` and root can access `/home/openclaw/.openclaw`. To edit config: use the Control UI once the gateway is running, or `sudo -u openclaw $EDITOR /home/openclaw/.openclaw/openclaw.json`.
|
||||
|
||||
## Environment and config
|
||||
|
||||
- **Token:** Stored in `~openclaw/.openclaw/.env` as `OPENCLAW_GATEWAY_TOKEN`. `setup-podman.sh` and `run-openclaw-podman.sh` generate it if missing (uses `openssl`, `python3`, or `od`).
|
||||
- **Optional:** In that `.env` you can set provider keys (e.g. `GROQ_API_KEY`, `OLLAMA_API_KEY`) and other OpenClaw env vars.
|
||||
- **Host ports:** By default the script maps `18789` (gateway) and `18790` (bridge). Override the **host** port mapping with `OPENCLAW_PODMAN_GATEWAY_HOST_PORT` and `OPENCLAW_PODMAN_BRIDGE_HOST_PORT` when launching.
|
||||
- **Gateway bind:** By default, `run-openclaw-podman.sh` starts the gateway with `--bind loopback` for safe local access. To expose on LAN, set `OPENCLAW_GATEWAY_BIND=lan` and configure `gateway.controlUi.allowedOrigins` (or explicitly enable host-header fallback) in `openclaw.json`.
|
||||
- **Paths:** Host config and workspace default to `~openclaw/.openclaw` and `~openclaw/.openclaw/workspace`. Override the host paths used by the launch script with `OPENCLAW_CONFIG_DIR` and `OPENCLAW_WORKSPACE_DIR`.
|
||||
|
||||
## Useful commands
|
||||
|
||||
- **Logs:** With quadlet: `sudo journalctl --machine openclaw@ --user -u openclaw.service -f`. With script: `sudo -u openclaw podman logs -f openclaw`
|
||||
- **Stop:** With quadlet: `sudo systemctl --machine openclaw@ --user stop openclaw.service`. With script: `sudo -u openclaw podman stop openclaw`
|
||||
- **Start again:** With quadlet: `sudo systemctl --machine openclaw@ --user start openclaw.service`. With script: re-run the launch script or `podman start openclaw`
|
||||
- **Remove container:** `sudo -u openclaw podman rm -f openclaw` — config and workspace on the host are kept
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
- **Permission denied (EACCES) on config or auth-profiles:** The container defaults to `--userns=keep-id` and runs as the same uid/gid as the host user running the script. Ensure your host `OPENCLAW_CONFIG_DIR` and `OPENCLAW_WORKSPACE_DIR` are owned by that user.
|
||||
- **Gateway start blocked (missing `gateway.mode=local`):** Ensure `~openclaw/.openclaw/openclaw.json` exists and sets `gateway.mode="local"`. `setup-podman.sh` creates this file if missing.
|
||||
- **Rootless Podman fails for user openclaw:** Check `/etc/subuid` and `/etc/subgid` contain a line for `openclaw` (e.g. `openclaw:100000:65536`). Add it if missing and restart.
|
||||
- **Container name in use:** The launch script uses `podman run --replace`, so the existing container is replaced when you start again. To clean up manually: `podman rm -f openclaw`.
|
||||
- **Script not found when running as openclaw:** Ensure `setup-podman.sh` was run so that `run-openclaw-podman.sh` is copied to openclaw’s home (e.g. `/home/openclaw/run-openclaw-podman.sh`).
|
||||
- **Quadlet service not found or fails to start:** Run `sudo systemctl --machine openclaw@ --user daemon-reload` after editing the `.container` file. Quadlet requires cgroups v2: `podman info --format '{{.Host.CgroupsVersion}}'` should show `2`.
|
||||
|
||||
## Optional: run as your own user
|
||||
|
||||
To run the gateway as your normal user (no dedicated openclaw user): build the image, create `~/.openclaw/.env` with `OPENCLAW_GATEWAY_TOKEN`, and run the container with `--userns=keep-id` and mounts to your `~/.openclaw`. The launch script is designed for the openclaw-user flow; for a single-user setup you can instead run the `podman run` command from the script manually, pointing config and workspace to your home. Recommended for most users: use `setup-podman.sh` and run as the openclaw user so config and process are isolated.
|
||||
106
content/install/railway.mdx
Normal file
106
content/install/railway.mdx
Normal file
@@ -0,0 +1,106 @@
|
||||
---
|
||||
title: 在 Railway 上部署
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T21:36:21Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: 6d5c2ec2f779bb240e778b5e18ffb8138ce175c4bbdf58b2064a6ad200bf4d1b
|
||||
source_path: railway.mdx
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
通过一键模板在 Railway 上部署 OpenClaw，并在浏览器中完成设置。
|
||||
这是最简单的"无需在服务器上使用终端"的方式：Railway 为你运行 Gateway网关，
|
||||
你只需通过 `/setup` 网页向导完成所有配置。
|
||||
|
||||
## 快速检查清单（新用户）
|
||||
|
||||
1. 点击下方的 **Deploy on Railway**。
|
||||
2. 添加一个挂载到 `/data` 的 **Volume**。
|
||||
3. 设置必需的**变量**（至少需要 `SETUP_PASSWORD`）。
|
||||
4. 在端口 `8080` 上启用 **HTTP Proxy**。
|
||||
5. 打开 `https://<your-railway-domain>/setup` 并完成向导。
|
||||
|
||||
## 一键部署
|
||||
|
||||
<a href="https://railway.com/deploy/clawdbot-railway-template" target="_blank" rel="noreferrer">
|
||||
Deploy on Railway
|
||||
</a>
|
||||
|
||||
部署完成后，在 **Railway → 你的服务 → Settings → Domains** 中找到你的公开 URL。
|
||||
|
||||
Railway 会：
|
||||
|
||||
- 为你生成一个域名（通常是 `https://<something>.up.railway.app`），或者
|
||||
- 使用你绑定的自定义域名。
|
||||
|
||||
然后打开：
|
||||
|
||||
- `https://<your-railway-domain>/setup` — 设置向导（需密码保护）
|
||||
- `https://<your-railway-domain>/openclaw` — 控制面板 UI
|
||||
|
||||
## 你将获得
|
||||
|
||||
- 托管的 OpenClaw Gateway网关 + 控制面板 UI
|
||||
- `/setup` 网页设置向导（无需终端命令）
|
||||
- 通过 Railway Volume（`/data`）实现持久化存储，配置/凭证/工作区在重新部署后不会丢失
|
||||
- 在 `/setup/export` 导出备份，方便日后从 Railway 迁移
|
||||
|
||||
## 必需的 Railway 设置
|
||||
|
||||
### 公共网络
|
||||
|
||||
为服务启用 **HTTP Proxy**。
|
||||
|
||||
- 端口：`8080`
|
||||
|
||||
### Volume（必需）
|
||||
|
||||
挂载一个 Volume 到：
|
||||
|
||||
- `/data`
|
||||
|
||||
### 变量
|
||||
|
||||
在服务上设置以下变量：
|
||||
|
||||
- `SETUP_PASSWORD`（必需）
|
||||
- `PORT=8080`（必需 — 必须与公共网络中的端口一致）
|
||||
- `OPENCLAW_STATE_DIR=/data/.openclaw`（推荐）
|
||||
- `OPENCLAW_WORKSPACE_DIR=/data/workspace`（推荐）
|
||||
- `OPENCLAW_GATEWAY_TOKEN`（推荐；请视为管理员密钥）
|
||||
|
||||
## 设置流程
|
||||
|
||||
1. 访问 `https://<your-railway-domain>/setup` 并输入你的 `SETUP_PASSWORD`。
|
||||
2. 选择模型/认证提供商并粘贴你的密钥。
|
||||
3. （可选）添加 Telegram/Discord/Slack 令牌。
|
||||
4. 点击 **Run setup**。
|
||||
|
||||
如果 Telegram 私信设置为配对模式，设置向导可以批准配对码。
|
||||
|
||||
## 获取聊天令牌
|
||||
|
||||
### Telegram 机器人令牌
|
||||
|
||||
1. 在 Telegram 中给 `@BotFather` 发消息
|
||||
2. 执行 `/newbot`
|
||||
3. 复制令牌（格式类似 `123456789:AA...`）
|
||||
4. 将其粘贴到 `/setup` 中
|
||||
|
||||
### Discord 机器人令牌
|
||||
|
||||
1. 前往 https://discord.com/developers/applications
|
||||
2. **New Application** → 选择一个名称
|
||||
3. **Bot** → **Add Bot**
|
||||
4. 在 Bot → Privileged Gateway Intents 下**启用 MESSAGE CONTENT INTENT**（必需，否则机器人启动时会崩溃）
|
||||
5. 复制 **Bot Token** 并粘贴到 `/setup` 中
|
||||
6. 邀请机器人加入你的服务器（OAuth2 URL Generator；scopes：`bot`、`applications.commands`）
|
||||
|
||||
## 备份与迁移
|
||||
|
||||
在以下地址下载备份：
|
||||
|
||||
- `https://<your-railway-domain>/setup/export`
|
||||
|
||||
这会导出你的 OpenClaw 状态和工作区，方便你迁移到其他主机而不丢失配置或记忆。
|
||||
169
content/install/render.mdx
Normal file
169
content/install/render.mdx
Normal file
@@ -0,0 +1,169 @@
|
||||
---
|
||||
title: 在 Render 上部署
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T21:38:27Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: 03f0f277145daf6012ce33a9e8447d2eaaf346dfdb0df57a61ebf90b18b67c65
|
||||
source_path: render.mdx
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
使用基础设施即代码方式在 Render 上部署 OpenClaw。内置的 `render.yaml` Blueprint 以声明式方式定义了你的整个技术栈——服务、磁盘、环境变量，让你只需一键即可完成部署，并将基础设施与代码一同进行版本管理。
|
||||
|
||||
## 前提条件
|
||||
|
||||
- 一个 [Render 账户](https://render.com)（提供免费套餐）
|
||||
- 来自你首选[模型提供商](/providers)的 API 密钥
|
||||
|
||||
## 使用 Render Blueprint 部署
|
||||
|
||||
<a
|
||||
href="https://render.com/deploy?repo=https://github.com/openclaw/openclaw"
|
||||
target="_blank"
|
||||
rel="noreferrer"
|
||||
>
|
||||
部署到 Render
|
||||
</a>
|
||||
|
||||
点击此链接将会：
|
||||
|
||||
1. 根据本仓库根目录下的 `render.yaml` Blueprint 创建一个新的 Render 服务。
|
||||
2. 提示你设置 `SETUP_PASSWORD`
|
||||
3. 构建 Docker 镜像并部署
|
||||
|
||||
部署完成后，你的服务 URL 格式为 `https://<service-name>.onrender.com`。
|
||||
|
||||
## 了解 Blueprint
|
||||
|
||||
Render Blueprint 是定义基础设施的 YAML 文件。本仓库中的 `render.yaml` 配置了运行 OpenClaw 所需的一切：
|
||||
|
||||
```yaml
|
||||
services:
|
||||
- type: web
|
||||
name: openclaw
|
||||
runtime: docker
|
||||
plan: starter
|
||||
healthCheckPath: /health
|
||||
envVars:
|
||||
- key: PORT
|
||||
value: "8080"
|
||||
- key: SETUP_PASSWORD
|
||||
sync: false # prompts during deploy
|
||||
- key: OPENCLAW_STATE_DIR
|
||||
value: /data/.openclaw
|
||||
- key: OPENCLAW_WORKSPACE_DIR
|
||||
value: /data/workspace
|
||||
- key: OPENCLAW_GATEWAY_TOKEN
|
||||
generateValue: true # auto-generates a secure token
|
||||
disk:
|
||||
name: openclaw-data
|
||||
mountPath: /data
|
||||
sizeGB: 1
|
||||
```
|
||||
|
||||
使用的关键 Blueprint 功能：
|
||||
|
||||
| 功能 | 用途 |
|
||||
| --------------------- | ---------------------------------------- |
|
||||
| `runtime: docker` | 从仓库的 Dockerfile 进行构建 |
|
||||
| `healthCheckPath` | Render 监控 `/health` 并重启不健康的实例 |
|
||||
| `sync: false` | 在部署时提示输入值（用于密钥） |
|
||||
| `generateValue: true` | 自动生成加密安全的值 |
|
||||
| `disk` | 持久化存储，在重新部署后数据仍然保留 |
|
||||
|
||||
## 选择套餐
|
||||
|
||||
| 套餐 | 休眠机制 | 磁盘 | 适用场景 |
|
||||
| --------- | ------------------ | ------ | ---------------- |
|
||||
| Free | 空闲 15 分钟后休眠 | 不可用 | 测试、演示 |
|
||||
| Starter | 永不休眠 | 1GB+ | 个人使用、小团队 |
|
||||
| Standard+ | 永不休眠 | 1GB+ | 生产环境、多渠道 |
|
||||
|
||||
Blueprint 默认使用 `starter`。如需使用免费套餐，请在你 fork 的 `render.yaml` 中将 `plan: free`（但请注意：没有持久化磁盘意味着每次部署后配置都会重置）。
|
||||
|
||||
## 部署完成后
|
||||
|
||||
### 完成设置向导
|
||||
|
||||
1. 访问 `https://<your-service>.onrender.com/setup`
|
||||
2. 输入你的 `SETUP_PASSWORD`
|
||||
3. 选择模型提供商并粘贴你的 API 密钥
|
||||
4. 可选配置消息渠道（Telegram、Discord、Slack）
|
||||
5. 点击 **Run setup**
|
||||
|
||||
### 访问控制面板
|
||||
|
||||
Web 管理面板位于 `https://<your-service>.onrender.com/openclaw`。
|
||||
|
||||
## Render 仪表盘功能
|
||||
|
||||
### 日志
|
||||
|
||||
在 **Dashboard → 你的服务 → Logs** 中查看实时日志。可按以下类型筛选：
|
||||
|
||||
- 构建日志（Docker 镜像创建）
|
||||
- 部署日志（服务启动）
|
||||
- 运行时日志（应用输出）
|
||||
|
||||
### Shell 访问
|
||||
|
||||
如需调试，可通过 **Dashboard → 你的服务 → Shell** 打开 shell 会话。持久化磁盘挂载在 `/data`。
|
||||
|
||||
### 环境变量
|
||||
|
||||
在 **Dashboard → 你的服务 → Environment** 中修改变量。更改会触发自动重新部署。
|
||||
|
||||
### 自动部署
|
||||
|
||||
如果你使用的是原始 OpenClaw 仓库，Render 不会自动部署你的 OpenClaw。要更新它，请在仪表盘中手动执行 Blueprint 同步。
|
||||
|
||||
## 自定义域名
|
||||
|
||||
1. 前往 **Dashboard → 你的服务 → Settings → Custom Domains**
|
||||
2. 添加你的域名
|
||||
3. 按照指引配置 DNS（CNAME 指向 `*.onrender.com`）
|
||||
4. Render 会自动配置 TLS 证书
|
||||
|
||||
## 扩展
|
||||
|
||||
Render 支持水平和垂直扩展：
|
||||
|
||||
- **垂直扩展**：更改套餐以获取更多 CPU/内存
|
||||
- **水平扩展**：增加实例数量（Standard 套餐及以上）
|
||||
|
||||
对于 OpenClaw，垂直扩展通常就足够了。水平扩展需要粘性会话或外部状态管理。
|
||||
|
||||
## 备份与迁移
|
||||
|
||||
随时导出你的配置和工作区：
|
||||
|
||||
```
|
||||
https://<your-service>.onrender.com/setup/export
|
||||
```
|
||||
|
||||
这将下载一个可移植的备份文件，你可以在任何 OpenClaw 主机上恢复。
|
||||
|
||||
## 故障排除
|
||||
|
||||
### 服务无法启动
|
||||
|
||||
在 Render 仪表盘中检查部署日志。常见问题：
|
||||
|
||||
- 缺少 `SETUP_PASSWORD` — Blueprint 会提示输入此值，但请确认已设置
|
||||
- 端口不匹配 — 确保 `PORT=8080` 与 Dockerfile 暴露的端口一致
|
||||
|
||||
### 冷启动缓慢（免费套餐）
|
||||
|
||||
免费套餐的服务在 15 分钟无活动后会休眠。休眠后的首次请求需要几秒钟等待容器启动。升级到 Starter 套餐可实现始终在线。
|
||||
|
||||
### 重新部署后数据丢失
|
||||
|
||||
这发生在免费套餐上（无持久化磁盘）。升级到付费套餐，或通过 `/setup/export` 定期导出你的配置。
|
||||
|
||||
### 健康检查失败
|
||||
|
||||
Render 期望在 30 秒内从 `/health` 获得 200 响应。如果构建成功但部署失败，可能是服务启动耗时过长。请检查：
|
||||
|
||||
- 构建日志中是否有错误
|
||||
- 容器是否能通过 `docker build && docker run` 在本地正常运行
|
||||
135
content/install/uninstall.md
Normal file
135
content/install/uninstall.md
Normal file
@@ -0,0 +1,135 @@
|
||||
---
|
||||
read_when:
|
||||
- 你想从机器上移除 OpenClaw
|
||||
- 卸载后 Gateway 网关服务仍在运行
|
||||
summary: 完全卸载 OpenClaw（CLI、服务、状态、工作区）
|
||||
title: 卸载
|
||||
x-i18n:
|
||||
generated_at: "2026-02-03T07:50:10Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: 6673a755c5e1f90a807dd8ac92a774cff6d1bc97d125c75e8bf72a40e952a777
|
||||
source_path: install/uninstall.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 卸载
|
||||
|
||||
两种方式：
|
||||
|
||||
- 如果 `openclaw` 仍已安装，使用**简单方式**。
|
||||
- 如果 CLI 已删除但服务仍在运行，使用**手动服务移除**。
|
||||
|
||||
## 简单方式（CLI 仍已安装）
|
||||
|
||||
推荐：使用内置卸载程序：
|
||||
|
||||
```bash
|
||||
openclaw uninstall
|
||||
```
|
||||
|
||||
非交互式（自动化 / npx）：
|
||||
|
||||
```bash
|
||||
openclaw uninstall --all --yes --non-interactive
|
||||
npx -y openclaw uninstall --all --yes --non-interactive
|
||||
```
|
||||
|
||||
手动步骤（效果相同）：
|
||||
|
||||
1. 停止 Gateway 网关服务：
|
||||
|
||||
```bash
|
||||
openclaw gateway stop
|
||||
```
|
||||
|
||||
2. 卸载 Gateway 网关服务（launchd/systemd/schtasks）：
|
||||
|
||||
```bash
|
||||
openclaw gateway uninstall
|
||||
```
|
||||
|
||||
3. 删除状态 + 配置：
|
||||
|
||||
```bash
|
||||
rm -rf "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}"
|
||||
```
|
||||
|
||||
如果你将 `OPENCLAW_CONFIG_PATH` 设置为状态目录外的自定义位置，也请删除该文件。
|
||||
|
||||
4. 删除你的工作区（可选，移除智能体文件）：
|
||||
|
||||
```bash
|
||||
rm -rf ~/.openclaw/workspace
|
||||
```
|
||||
|
||||
5. 移除 CLI 安装（选择你使用的那个）：
|
||||
|
||||
```bash
|
||||
npm rm -g openclaw
|
||||
pnpm remove -g openclaw
|
||||
bun remove -g openclaw
|
||||
```
|
||||
|
||||
6. 如果你安装了 macOS 应用：
|
||||
|
||||
```bash
|
||||
rm -rf /Applications/OpenClaw.app
|
||||
```
|
||||
|
||||
注意事项：
|
||||
|
||||
- 如果你使用了配置文件（`--profile` / `OPENCLAW_PROFILE`），对每个状态目录重复步骤 3（默认为 `~/.openclaw-<profile>`）。
|
||||
- 在远程模式下，状态目录位于 **Gateway 网关主机**上，因此也需要在那里运行步骤 1-4。
|
||||
|
||||
## 手动服务移除（CLI 未安装）
|
||||
|
||||
如果 Gateway 网关服务持续运行但 `openclaw` 缺失，请使用此方法。
|
||||
|
||||
### macOS（launchd）
|
||||
|
||||
默认标签是 `bot.molt.gateway`（或 `bot.molt.<profile>`；旧版 `com.openclaw.*` 可能仍然存在）：
|
||||
|
||||
```bash
|
||||
launchctl bootout gui/$UID/bot.molt.gateway
|
||||
rm -f ~/Library/LaunchAgents/bot.molt.gateway.plist
|
||||
```
|
||||
|
||||
如果你使用了配置文件，请将标签和 plist 名称替换为 `bot.molt.<profile>`。如果存在任何旧版 `com.openclaw.*` plist，请将其移除。
|
||||
|
||||
### Linux（systemd 用户单元）
|
||||
|
||||
默认单元名称是 `openclaw-gateway.service`（或 `openclaw-gateway-<profile>.service`）：
|
||||
|
||||
```bash
|
||||
systemctl --user disable --now openclaw-gateway.service
|
||||
rm -f ~/.config/systemd/user/openclaw-gateway.service
|
||||
systemctl --user daemon-reload
|
||||
```
|
||||
|
||||
### Windows（计划任务）
|
||||
|
||||
默认任务名称是 `OpenClaw Gateway`（或 `OpenClaw Gateway (<profile>)`）。
|
||||
任务脚本位于你的状态目录下。
|
||||
|
||||
```powershell
|
||||
schtasks /Delete /F /TN "OpenClaw Gateway"
|
||||
Remove-Item -Force "$env:USERPROFILE\.openclaw\gateway.cmd"
|
||||
```
|
||||
|
||||
如果你使用了配置文件，请删除匹配的任务名称和 `~\.openclaw-<profile>\gateway.cmd`。
|
||||
|
||||
## 普通安装 vs 源码检出
|
||||
|
||||
### 普通安装（install.sh / npm / pnpm / bun）
|
||||
|
||||
如果你使用了 `https://openclaw.ai/install.sh` 或 `install.ps1`，CLI 是通过 `npm install -g openclaw@latest` 安装的。
|
||||
使用 `npm rm -g openclaw` 移除（或 `pnpm remove -g` / `bun remove -g`，如果你是用那种方式安装的）。
|
||||
|
||||
### 源码检出（git clone）
|
||||
|
||||
如果你从仓库检出运行（`git clone` + `openclaw ...` / `bun run openclaw ...`）：
|
||||
|
||||
1. 在删除仓库**之前**卸载 Gateway 网关服务（使用上面的简单方式或手动服务移除）。
|
||||
2. 删除仓库目录。
|
||||
3. 按上述方式移除状态 + 工作区。
|
||||
233
content/install/updating.md
Normal file
233
content/install/updating.md
Normal file
@@ -0,0 +1,233 @@
|
||||
---
|
||||
read_when:
|
||||
- 更新 OpenClaw
|
||||
- 更新后出现问题
|
||||
summary: 安全更新 OpenClaw（全局安装或源码），以及回滚策略
|
||||
title: 更新
|
||||
x-i18n:
|
||||
generated_at: "2026-02-03T07:50:25Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: 38cccac0839f0f22403b6508cd94ba1b401133ffc1d92d4f7640b8d04e082317
|
||||
source_path: install/updating.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 更新
|
||||
|
||||
OpenClaw 发展迅速（尚未到"1.0"）。将更新视为发布基础设施：更新 → 运行检查 → 重启（或使用会重启的 `openclaw update`）→ 验证。
|
||||
|
||||
## 推荐：重新运行网站安装程序（原地升级）
|
||||
|
||||
**首选**的更新路径是重新运行网站上的安装程序。它会检测现有安装、原地升级，并在需要时运行 `openclaw doctor`。
|
||||
|
||||
```bash
|
||||
curl -fsSL https://openclaw.ai/install.sh | bash
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- 如果你不想再次运行新手引导向导，添加 `--no-onboard`。
|
||||
- 对于**源码安装**，使用：
|
||||
```bash
|
||||
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git --no-onboard
|
||||
```
|
||||
安装程序**仅**在仓库干净时才会执行 `git pull --rebase`。
|
||||
- 对于**全局安装**，脚本底层使用 `npm install -g openclaw@latest`。
|
||||
- 旧版说明：`clawdbot` 仍可作为兼容性垫片使用。
|
||||
|
||||
## 更新之前
|
||||
|
||||
- 了解你的安装方式：**全局**（npm/pnpm）还是**源码**（git clone）。
|
||||
- 了解你的 Gateway 网关运行方式：**前台终端**还是**受管理服务**（launchd/systemd）。
|
||||
- 快照你的定制内容：
|
||||
- 配置：`~/.openclaw/openclaw.json`
|
||||
- 凭证：`~/.openclaw/credentials/`
|
||||
- 工作区：`~/.openclaw/workspace`
|
||||
|
||||
## 更新（全局安装）
|
||||
|
||||
全局安装（选择一个）：
|
||||
|
||||
```bash
|
||||
npm i -g openclaw@latest
|
||||
```
|
||||
|
||||
```bash
|
||||
pnpm add -g openclaw@latest
|
||||
```
|
||||
|
||||
我们**不**推荐将 Bun 用于 Gateway 网关运行时（WhatsApp/Telegram 有 bug）。
|
||||
|
||||
切换更新渠道（git + npm 安装）：
|
||||
|
||||
```bash
|
||||
openclaw update --channel beta
|
||||
openclaw update --channel dev
|
||||
openclaw update --channel stable
|
||||
```
|
||||
|
||||
使用 `--tag <dist-tag|version>` 进行一次性安装指定标签/版本。
|
||||
|
||||
渠道语义和发布说明参见[开发渠道](/install/development-channels)。
|
||||
|
||||
注意：在 npm 安装上，Gateway 网关在启动时会记录更新提示（检查当前渠道标签）。通过 `update.checkOnStart: false` 禁用。
|
||||
|
||||
然后：
|
||||
|
||||
```bash
|
||||
openclaw doctor
|
||||
openclaw gateway restart
|
||||
openclaw health
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- 如果你的 Gateway 网关作为服务运行，`openclaw gateway restart` 优于杀死 PID。
|
||||
- 如果你固定在特定版本，参见下面的"回滚/固定"。
|
||||
|
||||
## 更新（`openclaw update`）
|
||||
|
||||
对于**源码安装**（git checkout），首选：
|
||||
|
||||
```bash
|
||||
openclaw update
|
||||
```
|
||||
|
||||
它运行一个相对安全的更新流程：
|
||||
|
||||
- 需要干净的工作树。
|
||||
- 切换到选定的渠道（标签或分支）。
|
||||
- 获取并 rebase 到配置的上游（dev 渠道）。
|
||||
- 安装依赖、构建、构建控制 UI，并运行 `openclaw doctor`。
|
||||
- 默认重启 Gateway 网关（使用 `--no-restart` 跳过）。
|
||||
|
||||
如果你通过 **npm/pnpm** 安装（没有 git 元数据），`openclaw update` 将尝试通过你的包管理器更新。如果无法检测到安装，请改用"更新（全局安装）"。
|
||||
|
||||
## 更新（控制 UI / RPC）
|
||||
|
||||
控制 UI 有**更新并重启**（RPC：`update.run`）。它：
|
||||
|
||||
1. 运行与 `openclaw update` 相同的源码更新流程（仅限 git checkout）。
|
||||
2. 写入带有结构化报告（stdout/stderr 尾部）的重启哨兵。
|
||||
3. 重启 Gateway 网关并向最后活跃的会话 ping 报告。
|
||||
|
||||
如果 rebase 失败，Gateway 网关会中止并在不应用更新的情况下重启。
|
||||
|
||||
## 更新（从源码）
|
||||
|
||||
从仓库 checkout：
|
||||
|
||||
首选：
|
||||
|
||||
```bash
|
||||
openclaw update
|
||||
```
|
||||
|
||||
手动（大致等效）：
|
||||
|
||||
```bash
|
||||
git pull
|
||||
pnpm install
|
||||
pnpm build
|
||||
pnpm ui:build # 首次运行时自动安装 UI 依赖
|
||||
openclaw doctor
|
||||
openclaw health
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- 当你运行打包的 `openclaw` 二进制文件（[`openclaw.mjs`](https://github.com/openclaw/openclaw/blob/main/openclaw.mjs)）或使用 Node 运行 `dist/` 时，`pnpm build` 很重要。
|
||||
- 如果你从仓库 checkout 运行而没有全局安装，CLI 命令使用 `pnpm openclaw ...`。
|
||||
- 如果你直接从 TypeScript 运行（`pnpm openclaw ...`），通常不需要重新构建，但**配置迁移仍然适用** → 运行 doctor。
|
||||
- 在全局和 git 安装之间切换很容易：安装另一种方式，然后运行 `openclaw doctor` 以便将 Gateway 网关服务入口点重写为当前安装。
|
||||
|
||||
## 始终运行：`openclaw doctor`
|
||||
|
||||
Doctor 是"安全更新"命令。它故意很无聊：修复 + 迁移 + 警告。
|
||||
|
||||
注意：如果你是**源码安装**（git checkout），`openclaw doctor` 会提供先运行 `openclaw update`。
|
||||
|
||||
它通常做的事情：
|
||||
|
||||
- 迁移已弃用的配置键/旧版配置文件位置。
|
||||
- 审计私信策略并对有风险的"开放"设置发出警告。
|
||||
- 检查 Gateway 网关健康状况，可以提供重启。
|
||||
- 检测并将旧版 Gateway 网关服务（launchd/systemd；旧版 schtasks）迁移到当前 OpenClaw 服务。
|
||||
- 在 Linux 上，确保 systemd 用户 lingering（这样 Gateway 网关在登出后仍能存活）。
|
||||
|
||||
详情：[Doctor](/gateway/doctor)
|
||||
|
||||
## 启动/停止/重启 Gateway 网关
|
||||
|
||||
CLI（无论操作系统都适用）：
|
||||
|
||||
```bash
|
||||
openclaw gateway status
|
||||
openclaw gateway stop
|
||||
openclaw gateway restart
|
||||
openclaw gateway --port 18789
|
||||
openclaw logs --follow
|
||||
```
|
||||
|
||||
如果你使用受管理服务：
|
||||
|
||||
- macOS launchd（应用捆绑的 LaunchAgent）：`launchctl kickstart -k gui/$UID/bot.molt.gateway`（使用 `bot.molt.<profile>`；旧版 `com.openclaw.*` 仍然有效）
|
||||
- Linux systemd 用户服务：`systemctl --user restart openclaw-gateway[-<profile>].service`
|
||||
- Windows（WSL2）：`systemctl --user restart openclaw-gateway[-<profile>].service`
|
||||
- `launchctl`/`systemctl` 仅在服务已安装时有效；否则运行 `openclaw gateway install`。
|
||||
|
||||
运行手册 + 确切的服务标签：[Gateway 网关运行手册](/gateway)
|
||||
|
||||
## 回滚/固定（当出问题时）
|
||||
|
||||
### 固定（全局安装）
|
||||
|
||||
安装已知良好的版本（将 `<version>` 替换为最后可用的版本）：
|
||||
|
||||
```bash
|
||||
npm i -g openclaw@<version>
|
||||
```
|
||||
|
||||
```bash
|
||||
pnpm add -g openclaw@<version>
|
||||
```
|
||||
|
||||
提示：要查看当前发布的版本，运行 `npm view openclaw version`。
|
||||
|
||||
然后重启 + 重新运行 doctor：
|
||||
|
||||
```bash
|
||||
openclaw doctor
|
||||
openclaw gateway restart
|
||||
```
|
||||
|
||||
### 按日期固定（源码）
|
||||
|
||||
选择某个日期的提交（示例："2026-01-01 时 main 的状态"）：
|
||||
|
||||
```bash
|
||||
git fetch origin
|
||||
git checkout "$(git rev-list -n 1 --before=\"2026-01-01\" origin/main)"
|
||||
```
|
||||
|
||||
然后重新安装依赖 + 重启：
|
||||
|
||||
```bash
|
||||
pnpm install
|
||||
pnpm build
|
||||
openclaw gateway restart
|
||||
```
|
||||
|
||||
如果你之后想回到最新版本：
|
||||
|
||||
```bash
|
||||
git checkout main
|
||||
git pull
|
||||
```
|
||||
|
||||
## 如果你卡住了
|
||||
|
||||
- 再次运行 `openclaw doctor` 并仔细阅读输出（它通常会告诉你修复方法）。
|
||||
- 查看：[故障排除](/gateway/troubleshooting)
|
||||
- 在 Discord 上提问：https://discord.gg/clawd
|
||||
47
content/install/vps.md
Normal file
47
content/install/vps.md
Normal file
@@ -0,0 +1,47 @@
|
||||
---
|
||||
read_when:
|
||||
- 你想在云端运行 Gateway 网关
|
||||
- 你需要 VPS/托管指南的快速索引
|
||||
summary: OpenClaw 的 VPS 托管中心（Oracle/Fly/Hetzner/GCP/exe.dev）
|
||||
title: VPS 托管
|
||||
x-i18n:
|
||||
generated_at: "2026-02-03T10:12:57Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: 7749b479b333aa5541e7ad8b0ff84e9f8f6bd10d7188285121975cb893acc037
|
||||
source_path: vps.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# VPS 托管
|
||||
|
||||
本中心链接到支持的 VPS/托管指南，并在高层次上解释云部署的工作原理。
|
||||
|
||||
## 选择提供商
|
||||
|
||||
- **Railway**（一键 + 浏览器设置）：[Railway](/install/railway)
|
||||
- **Northflank**（一键 + 浏览器设置）：[Northflank](/install/northflank)
|
||||
- **Oracle Cloud（永久免费）**：[Oracle](/platforms/oracle) — $0/月（永久免费，ARM；容量/注册可能不太稳定）
|
||||
- **Fly.io**：[Fly.io](/install/fly)
|
||||
- **Hetzner（Docker）**：[Hetzner](/install/hetzner)
|
||||
- **GCP（Compute Engine）**：[GCP](/install/gcp)
|
||||
- **exe.dev**（VM + HTTPS 代理）：[exe.dev](/install/exe-dev)
|
||||
- **AWS（EC2/Lightsail/免费套餐）**：也运行良好。视频指南：
|
||||
https://x.com/techfrenAJ/status/2014934471095812547
|
||||
|
||||
## 云设置的工作原理
|
||||
|
||||
- **Gateway 网关运行在 VPS 上**并拥有状态 + 工作区。
|
||||
- 你通过**控制 UI** 或 **Tailscale/SSH** 从笔记本电脑/手机连接。
|
||||
- 将 VPS 视为数据源并**备份**状态 + 工作区。
|
||||
- 安全默认：将 Gateway 网关保持在 loopback 上，通过 SSH 隧道或 Tailscale Serve 访问。
|
||||
如果你绑定到 `lan`/`tailnet`，需要 `gateway.auth.token` 或 `gateway.auth.password`。
|
||||
|
||||
远程访问：[Gateway 网关远程访问](/gateway/remote)
|
||||
平台中心：[平台](/platforms)
|
||||
|
||||
## 在 VPS 上使用节点
|
||||
|
||||
你可以将 Gateway 网关保持在云端，并在本地设备（Mac/iOS/Android/无头）上配对**节点**。节点提供本地屏幕/摄像头/canvas 和 `system.run` 功能，而 Gateway 网关保持在云端。
|
||||
|
||||
文档：[节点](/nodes)，[节点 CLI](/cli/nodes)
|
||||
Reference in New Issue
Block a user