mirror of
https://github.com/farcasclaudiu/openclaw.git
synced 2026-06-29 01:02:03 +03:00
docs: restructure Get Started tab and improve onboarding flow (#9950)
* docs: restructure Get Started tab and improve onboarding flow - Flatten nested Onboarding group into linear First Steps flow - Add 'What is OpenClaw?' narrative section to landing page - Split wizard.md into streamlined overview + full reference (reference/wizard.md) - Move Pairing to Channels > Configuration - Move Bootstrapping to Agents > Fundamentals - Move macOS app onboarding to Platforms > macOS companion app - Move Lore to Help > Community - Remove duplicate install instructions from openclaw.md - Mirror navigation changes in zh-CN tabs - No content deleted — all detail preserved or relocated * docs: move deployment pages to install/, fix Platforms tab routing, clarify onboarding paths - Move deployment guides (fly, hetzner, gcp, macos-vm, exe-dev, railway, render, northflank) from platforms/ and root to install/ - Add 'Hosting and deployment' group to Install tab - Slim Gateway & Ops 'Remote access and deployment' down to 'Remote access' - Swap Platforms tab before Gateway & Ops to fix path-prefix routing - Move macOS app onboarding into First steps (parallel to CLI wizard) - Rename sidebar titles to 'Onboarding: CLI' / 'Onboarding: macOS App' - Add redirects for all moved paths - Update all internal links (en + zh-CN) - Fix img tag syntax in onboarding.md
This commit is contained in:
Seb Slight
@@ -70,7 +70,7 @@ Docker 是**可选的**。仅当你想要容器化的 Gateway 网关或验证 Do
|
||||
- `~/.openclaw/`
|
||||
- `~/.openclaw/workspace`
|
||||
|
||||
在 VPS 上运行？参阅 [Hetzner（Docker VPS）](/platforms/hetzner)。
|
||||
在 VPS 上运行？参阅 [Hetzner（Docker VPS）](/install/hetzner)。
|
||||
|
||||
### 手动流程（compose）
|
||||
|
||||
|
||||
@@ -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)
|
||||
@@ -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/)。
|
||||
@@ -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)
|
||||
@@ -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 容器 | 临时的 | 可重启 | 可以安全销毁 |
|
||||
@@ -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)（替代隔离方案）
|
||||
@@ -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`）
|
||||
@@ -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 状态和工作区，方便你迁移到其他主机而不丢失配置或记忆。
|
||||
@@ -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` 在本地正常运行
|
||||
Reference in New Issue
Block a user