![[OpenClaw 文档]安装--托管与部署](https://minio.imgdata.cn/cnesa/cnesa/2026/05/29/765544625aa111cd7ec16c796667c69f.png)
本文档汇总了 OpenClaw 官方文档站 安装 > 托管与部署 子模块下的全部 9 篇内容,源自 docs.openclaw.ai/zh-CN。
📄 Linux 服务器
原文:https://docs.openclaw.ai/zh-CN/vps
在任何 Linux 服务器或云 VPS 上运行 OpenClaw Gateway 网关。本页面帮助你选择提供商,解释云部署的工作方式,并介绍适用于各处的通用 Linux 调优。
选择提供商
AWS(EC2 / Lightsail / 免费层级)也能很好地工作。
社区视频演示可在
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 网关远程访问、平台中心。
先加固管理员访问
在公共 VPS 上安装 OpenClaw 之前,先决定你想如何管理机器本身。
- 如果你想要仅 Tailnet 的管理员访问,请先安装 Tailscale,将 VPS 加入你的 tailnet,通过 Tailscale IP 或 MagicDNS 名称验证第二个 SSH 会话,然后限制公共 SSH。
- 如果你没有使用 Tailscale,请在暴露更多服务之前,对你的 SSH 路径应用等效加固。
- 这与 Gateway 网关访问是分开的。你仍然可以将 OpenClaw 绑定到 loopback,并使用 SSH 隧道或 Tailscale Serve 访问仪表板。
Tailscale 专用的 Gateway 网关选项位于 Tailscale。
VPS 上的共享公司智能体
当每个用户都处于同一信任边界内,并且该智能体仅用于业务时,为团队运行单个智能体是有效的设置。
- 将它保持在专用运行时上(VPS/VM/容器 + 专用 OS 用户/账户)。
- 不要让该运行时登录个人 Apple/Google 账户或个人浏览器/密码管理器配置文件。
- 如果用户彼此对抗,请按 Gateway 网关/主机/OS 用户拆分。
安全模型详情:安全。
将节点与 VPS 配合使用
你可以将 Gateway 网关保留在云端,并在本地设备(Mac/iOS/Android/无头设备)上配对节点。节点提供本地屏幕/摄像头/画布和 system.run 能力,而 Gateway 网关保留在云端。
小型 VM 和 ARM 主机的启动调优
如果 CLI 命令在低功耗 VM(或 ARM 主机)上感觉较慢,请启用 Node 的模块编译缓存:
grep -q 'NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache' ~/.bashrc || cat >> ~/.bashrc <<'EOF'
export NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache
mkdir -p /var/tmp/openclaw-compile-cache
export OPENCLAW_NO_RESPAWN=1
EOF
source ~/.bashrc
NODE_COMPILE_CACHE可改善重复命令的启动时间。OPENCLAW_NO_RESPAWN=1可避免自重生路径带来的额外启动开销。- 第一次命令运行会预热缓存;后续运行会更快。
- 有关 Raspberry Pi 的具体信息,请参阅 Raspberry Pi。
systemd 调优检查清单(可选)
对于使用 systemd 的 VM 主机,请考虑:
- 为稳定的启动路径添加服务 env:
OPENCLAW_NO_RESPAWN=1NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache- 保持重启行为明确:
Restart=alwaysRestartSec=2TimeoutStartSec=90- 状态/缓存路径优先使用 SSD 支持的磁盘,以减少随机 I/O 冷启动损耗。
对于标准的 openclaw onboard --install-daemon 路径,请编辑用户单元:
systemctl --user edit openclaw-gateway.service
[Service]
Environment=OPENCLAW_NO_RESPAWN=1
Environment=NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache
Restart=always
RestartSec=2
TimeoutStartSec=90
如果你有意安装了系统单元,请改为通过 sudo systemctl edit openclaw-gateway.service 编辑 openclaw-gateway.service。
Restart= 策略如何帮助自动恢复:
systemd 可以自动化服务恢复。
有关 Linux OOM 行为、子进程受害者选择以及 exit 137 诊断,请参阅 Linux 内存压力和 OOM 终止。
相关
📄 Fly.io
原文:https://docs.openclaw.ai/zh-CN/install/fly
目标: 在 Fly.io 机器上运行 OpenClaw Gateway 网关,并具备持久存储、自动 HTTPS,以及 Discord/渠道访问能力。
你需要准备
- 已安装 flyctl CLI
- Fly.io 账号(免费层级可用)
- 模型凭证:你选择的模型提供商的 API key
- 渠道凭证:Discord bot token、Telegram token 等。
新手快速路径
- 克隆仓库 → 自定义
fly.toml - 创建应用 + 卷 → 设置密钥
- 使用
fly deploy部署 - SSH 进入以创建配置,或使用 Control UI
```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`(圣何塞)。
编辑 fly.toml,使其匹配你的应用名称和需求。
**安全注意事项:** 默认配置会暴露一个公开 URL。若要使用没有公网 IP 的加固部署,请参阅[私有部署](#private-deployment-hardened),或使用 `deploy/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"
```
OpenClaw Docker 镜像使用 `tini` 作为其入口点。Fly 进程命令会替换 Docker `CMD`,但不会替换 `ENTRYPOINT`,因此进程仍会在 `tini` 下运行。
**关键设置:**
| 设置 | 原因 |
| ------------------------------ | --------------------------------------------------------------------------- |
| `--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"` | 将状态持久化到卷上 |
```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...
```
**注意:**
- 非 local loopback 绑定(`--bind lan`)需要有效的 Gateway 网关认证路径。这个 Fly.io 示例使用 `OPENCLAW_GATEWAY_TOKEN`,但 `gateway.auth.password` 或正确配置的非 local loopback `trusted-proxy` 部署也满足要求。
- 像对待密码一样对待这些 token。
- **对于所有 API key 和 token,优先使用环境变量而不是配置文件**。这样可以避免密钥进入 `openclaw.json`,从而降低被意外暴露或记录到日志中的风险。
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
```
SSH 进入机器以创建正确的配置:
```bash
fly ssh console
```
创建配置目录和文件:
```bash
mkdir -p /data
cat > /data/openclaw.json << 'EOF'
{
"agents": {
"defaults": {
"model": {
"primary": "anthropic/claude-opus-4-6",
"fallbacks": ["anthropic/claude-sonnet-4-6", "openai/gpt-5.4"]
},
"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",
"controlUi": {
"allowedOrigins": [
"https://my-openclaw.fly.dev",
"http://localhost:3000",
"http://127.0.0.1:3000"
]
}
},
"meta": {}
}
EOF
```
**注意:** 设置 `OPENCLAW_STATE_DIR=/data` 后,配置路径是 `/data/openclaw.json`。
**注意:** 将 `https://my-openclaw.fly.dev` 替换为你真实的 Fly 应用源。Gateway 网关启动时会根据运行时 `--bind` 和 `--port` 值初始化本地 Control UI 源,因此首次启动可以在配置尚不存在时继续进行,但通过 Fly 的浏览器访问仍需要在 `gateway.controlUi.allowedOrigins` 中列出精确的 HTTPS 源。
**注意:** Discord token 可以来自以下任一位置:
- 环境变量:`DISCORD_BOT_TOKEN`(推荐用于密钥)
- 配置文件:`channels.discord.token`
如果使用环境变量,就不需要将 token 添加到配置中。Gateway 网关会自动读取 `DISCORD_BOT_TOKEN`。
重启以应用:
```bash
exit
fly machine restart <machine-id>
```
### Control UI
在浏览器中打开:
```bash
fly open
```
或访问 `https://my-openclaw.fly.dev/`
使用已配置的共享密钥进行认证。本指南使用来自 `OPENCLAW_GATEWAY_TOKEN` 的 Gateway 网关 token;如果你切换到了密码认证,请改用该密码。
### 日志
```bash
fly logs # Live logs
fly logs --no-tail # Recent logs
```
### SSH 控制台
```bash
fly ssh console
```
故障排除
“应用未在预期地址上监听”
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 中增加内存:
[[vm]]
memory = "2048mb"
或更新现有机器:
fly machine update <machine-id> --vm-memory 2048 -y
注意: 512MB 太小。1GB 可能可用,但在负载较高或日志较详细时可能 OOM。建议使用 2GB。
Gateway 网关锁问题
Gateway 网关因 “already running” 错误而拒绝启动。
当容器重启但 PID 锁文件仍保留在卷上时,会出现这种情况。
修复: 删除锁文件:
fly ssh console --command "rm -f /data/gateway.*.lock"
fly machine restart <machine-id>
锁文件位于 /data/gateway.*.lock(不在子目录中)。
配置未被读取
--allow-unconfigured 只会绕过启动保护。它不会创建或修复 /data/openclaw.json,因此当你想要正常启动本地 Gateway 网关时,请确保真实配置存在,并且包含 gateway.mode="local"。
验证配置是否存在:
fly ssh console --command "cat /data/openclaw.json"
通过 SSH 写入配置
fly ssh console -C 命令不支持 shell 重定向。要写入配置文件:
# 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 可能会失败。请先删除:
fly ssh console --command "rm /data/openclaw.json"
状态未持久化
如果重启后丢失认证配置、渠道/提供商状态或会话,则说明状态目录正在写入容器文件系统。
修复: 确保 fly.toml 中设置了 OPENCLAW_STATE_DIR=/data,然后重新部署。
更新
# Pull latest changes
git pull
# Redeploy
fly deploy
# Check health
fly status
fly logs
更新机器命令
如果你需要在不完整重新部署的情况下更改启动命令:
# 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 等)发现。
对于没有公网暴露的加固部署,请使用私有模板。
何时使用私有部署
- 你只发起出站调用/消息(没有入站 webhook)
- 你使用 ngrok 或 Tailscale 隧道处理任何 webhook 回调
- 你通过 SSH、代理或 WireGuard 访问 Gateway 网关,而不是通过浏览器
- 你希望该部署不被互联网扫描器发现
设置
使用 deploy/fly.private.toml,而不是标准配置:
# Deploy with private config
fly deploy -c deploy/fly.private.toml
或转换现有部署:
# 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 deploy/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:本地代理(最简单)
# Forward local port 3000 to the app
fly proxy 3000:3000 -a my-openclaw
# Then open http://localhost:3000 in browser
选项 2:WireGuard VPN
# 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
fly ssh console -a my-openclaw
私有部署中的 Webhook
如果你需要在不公开暴露的情况下接收 Webhook 回调(Twilio、Telnyx 等):
- ngrok 隧道 - 在容器内或作为 sidecar 运行 ngrok
- Tailscale Funnel - 通过 Tailscale 暴露特定路径
- 仅出站 - 一些提供商(Twilio)无需 Webhook 即可正常处理出站呼叫
使用 ngrok 的语音呼叫配置示例:
{
plugins: {
entries: {
"voice-call": {
enabled: true,
config: {
provider: "twilio",
tunnel: { provider: "ngrok" },
webhookSecurity: {
allowedHosts: ["example.ngrok.app"],
},
},
},
},
},
}
ngrok 隧道在容器内运行,并提供一个公开的 Webhook URL,而不会暴露 Fly 应用本身。将 webhookSecurity.allowedHosts 设置为公开隧道主机名,以便接受转发的 host 标头。
安全优势
| 方面 | 公开 | 私有 |
|---|---|---|
| 互联网扫描器 | 可发现 | 隐藏 |
| 直接攻击 | 可能 | 被阻止 |
| 控制 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 定价。
后续步骤
- 设置消息渠道:Channels
- 配置 Gateway 网关:Gateway 网关配置
- 让 OpenClaw 保持最新:更新
相关内容
📄 Hetzner
原文:https://docs.openclaw.ai/zh-CN/install/hetzner
目标
使用 Docker 在 Hetzner VPS 上运行一个持久化的 OpenClaw Gateway 网关,并具备持久状态、内置二进制文件和安全的重启行为。
如果你想要“每月约 5 美元的 OpenClaw 24/7”,这是最简单可靠的设置方式。
Hetzner 定价会变化;选择最小的 Debian/Ubuntu VPS,如果遇到 OOM,再向上扩容。
安全模型提醒:
- 当所有人都在同一信任边界内,且运行时仅用于业务时,公司共享的智能体没有问题。
- 保持严格隔离:专用 VPS/运行时 + 专用账号;不要在该主机上使用个人 Apple/Google/浏览器/密码管理器配置文件。
- 如果用户之间互不信任,请按 Gateway 网关/主机/OS 用户拆分。
我们在做什么(简单来说)?
- 租用一台小型 Linux 服务器(Hetzner VPS)
- 安装 Docker(隔离的应用运行时)
- 在 Docker 中启动 OpenClaw Gateway 网关
- 在主机上持久化
~/.openclaw+~/.openclaw/workspace(重启/重建后仍保留) - 通过 SSH 隧道从你的笔记本电脑访问控制 UI
挂载的 ~/.openclaw 状态包含 openclaw.json、每个智能体的
agents/<agentId>/agent/auth-profiles.json 以及 .env。
可以通过以下方式访问 Gateway 网关:
- 从你的笔记本电脑进行 SSH 端口转发
- 如果你自行管理防火墙和令牌,也可以直接暴露端口
本指南假设 Hetzner 上运行的是 Ubuntu 或 Debian。
如果你使用的是其他 Linux VPS,请相应映射软件包。
通用 Docker 流程请参阅 Docker。
快速路径(有经验的运维人员)
- 预置 Hetzner VPS
- 安装 Docker
- 克隆 OpenClaw 仓库
- 创建持久化主机目录
- 配置
.env和docker-compose.yml - 将所需二进制文件内置到镜像中
docker compose up -d- 验证持久化和 Gateway 网关访问
你需要什么
- 拥有 root 访问权限的 Hetzner VPS
- 从你的笔记本电脑进行 SSH 访问
- 基本熟悉 SSH + 复制/粘贴
- 约 20 分钟
- Docker 和 Docker Compose
- 模型认证凭据
- 可选提供商凭据
- WhatsApp 二维码
- Telegram 机器人令牌
- Gmail OAuth
在 Hetzner 中创建一台 Ubuntu 或 Debian VPS。
以 root 身份连接:
```bash
ssh root@YOUR_VPS_IP
```
本指南假设该 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
```
bash
git clone https://github.com/openclaw/openclaw.git
cd openclaw
本指南假设你会构建一个自定义镜像,以保证二进制文件持久存在。
Docker 容器是临时的。
所有长期状态都必须存放在主机上。
```bash
mkdir -p /root/.openclaw/workspace
# Set ownership to the container user (uid 1000):
chown -R 1000:1000 /root/.openclaw
```
在仓库根目录中创建 .env。
```bash
OPENCLAW_IMAGE=openclaw:latest
OPENCLAW_GATEWAY_TOKEN=
OPENCLAW_GATEWAY_BIND=lan
OPENCLAW_GATEWAY_PORT=18789
OPENCLAW_CONFIG_DIR=/root/.openclaw
OPENCLAW_WORKSPACE_DIR=/root/.openclaw/workspace
GOG_KEYRING_PASSWORD=
XDG_CONFIG_HOME=/home/node/.openclaw
```
如果你想通过 `.env` 管理稳定的 Gateway 网关
令牌,请设置 `OPENCLAW_GATEWAY_TOKEN`;否则,请先配置 `gateway.auth.token`,
再依赖客户端在重启后继续使用。如果两个来源都不存在,OpenClaw 会为该次启动
使用仅运行时令牌。生成一个密钥环密码,并将其粘贴到 `GOG_KEYRING_PASSWORD`:
```bash
openssl rand -hex 32
```
**不要提交此文件。**
此 `.env` 文件用于容器/运行时环境变量,例如 `OPENCLAW_GATEWAY_TOKEN`。
存储的提供商 OAuth/API-key 身份验证位于挂载的
`~/.openclaw/agents/<agentId>/agent/auth-profiles.json`。
创建或更新 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:
# Recommended: keep the Gateway loopback-only on the VPS; access via SSH tunnel.
# To expose it publicly, remove the `127.0.0.1:` prefix and firewall accordingly.
- "127.0.0.1:${OPENCLAW_GATEWAY_PORT}:18789"
command:
[
"node",
"dist/index.js",
"gateway",
"--bind",
"${OPENCLAW_GATEWAY_BIND}",
"--port",
"${OPENCLAW_GATEWAY_PORT}",
"--allow-unconfigured",
]
```
`--allow-unconfigured` 仅用于便捷引导,它不能替代正确的 Gateway 网关配置。仍需设置身份验证(`gateway.auth.token` 或密码),并为你的部署使用安全的绑定设置。
通用 Docker 主机流程请使用共享运行时指南:
- [将所需二进制文件烘焙进镜像](/zh-CN/install/docker-vm-runtime#bake-required-binaries-into-the-image)
- [构建并启动](/zh-CN/install/docker-vm-runtime#build-and-launch)
- [哪些内容会持久化到哪里](/zh-CN/install/docker-vm-runtime#what-persists-where)
- [更新](/zh-CN/install/docker-vm-runtime#updates)
完成共享的构建和启动步骤后,完成以下设置以打开隧道:
**前提条件:**确保你的 VPS sshd 配置允许 TCP 转发。如果你
加固过 SSH 配置,请检查 `/etc/ssh/sshd_config` 并设置:
```
AllowTcpForwarding local
```
`local` 允许从你的笔记本电脑使用 `ssh -L` 本地转发,同时阻止
来自服务器的远程转发。将其设置为 `no` 会导致隧道失败,
并显示:
`channel 3: open failed: administratively prohibited: open failed`
确认已启用 TCP 转发后,重启 SSH 服务
(`systemctl restart ssh`),并从你的笔记本电脑运行隧道:
```bash
ssh -N -L 18789:127.0.0.1:18789 root@YOUR_VPS_IP
```
打开:
`http://127.0.0.1:18789/`
粘贴已配置的共享密钥。本指南默认使用 Gateway 网关令牌;如果你已切换到密码身份验证,请改用该密码。
共享持久化映射位于 Docker VM Runtime。
基础设施即代码(Terraform)
对于偏好基础设施即代码工作流的团队,社区维护的 Terraform 设置提供:
- 带远程状态管理的模块化 Terraform 配置
- 通过 cloud-init 自动预配
- 部署脚本(引导、部署、备份/恢复)
- 安全加固(防火墙、UFW、仅限 SSH 访问)
- 用于 Gateway 网关访问的 SSH 隧道配置
仓库:
- 基础设施:openclaw-terraform-hetzner
- Docker 配置:openclaw-docker-config
这种方式通过可复现部署、版本控制的基础设施和自动化灾难恢复,补充了上面的 Docker 设置。
由社区维护。有关问题或贡献,请参见上面的仓库链接。
后续步骤
- 设置消息渠道:渠道
- 配置 Gateway 网关:Gateway 网关配置
- 使 OpenClaw 保持最新:更新
相关内容
📄 GCP
原文:https://docs.openclaw.ai/zh-CN/install/gcp
使用 Docker 在 GCP Compute Engine VM 上运行持久化的 OpenClaw Gateway 网关,并具备持久状态、内置二进制文件和安全重启行为。
如果你想要“每月约 5-12 美元的 24/7 OpenClaw”,这是 Google Cloud 上的可靠设置。
价格会因机器类型和区域而异;选择能满足工作负载的最小 VM,如果遇到 OOM 再扩容。
我们要做什么(简单来说)?
- 创建 GCP 项目并启用结算
- 创建 Compute Engine VM
- 安装 Docker(隔离的应用运行时)
- 在 Docker 中启动 OpenClaw Gateway 网关
- 在主机上持久化
~/.openclaw+~/.openclaw/workspace(重启/重建后仍保留) - 通过 SSH 隧道从你的笔记本访问控制 UI
挂载的 ~/.openclaw 状态包括 openclaw.json、每个智能体的
agents/<agentId>/agent/auth-profiles.json,以及 .env。
可以通过以下方式访问 Gateway 网关:
- 从你的笔记本进行 SSH 端口转发
- 如果你自行管理防火墙和令牌,也可以直接暴露端口
本指南使用 GCP Compute Engine 上的 Debian。
Ubuntu 也可使用;请对应调整软件包。
通用 Docker 流程请参见 Docker。
快速路径(有经验的运维人员)
- 创建 GCP 项目 + 启用 Compute Engine API
- 创建 Compute Engine VM(e2-small、Debian 12、20GB)
- SSH 进入 VM
- 安装 Docker
- 克隆 OpenClaw 仓库
- 创建持久化主机目录
- 配置
.env和docker-compose.yml - 内置所需二进制文件,构建并启动
你需要什么
- GCP 账号(e2-micro 符合免费层条件)
- 已安装 gcloud CLI(或使用 Cloud Console)
- 从你的笔记本进行 SSH 访问
- 基本熟悉 SSH + 复制/粘贴
- 约 20-30 分钟
- Docker 和 Docker Compose
- 模型认证凭证
- 可选提供商凭证
- WhatsApp 二维码
- Telegram bot 令牌
- Gmail OAuth
选项 A:gcloud CLI(推荐用于自动化)
从 [https://cloud.google.com/sdk/docs/install](https://cloud.google.com/sdk/docs/install) 安装
初始化并认证:
```bash
gcloud init
gcloud auth login
```
**选项 B:Cloud Console**
所有步骤都可以通过 [https://console.cloud.google.com](https://console.cloud.google.com) 的网页 UI 完成
CLI:
```bash
gcloud projects create my-openclaw-project --name="OpenClaw Gateway"
gcloud config set project my-openclaw-project
```
在 [https://console.cloud.google.com/billing](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
机器类型:
| 类型 | 规格 | 费用 | 备注 |
| --------- | ------------------------ | ------------------ | -------------------------------------------- |
| e2-medium | 2 vCPU,4GB RAM | 约 25 美元/月 | 本地 Docker 构建最可靠 |
| e2-small | 2 vCPU,2GB RAM | 约 12 美元/月 | Docker 构建的最低推荐配置 |
| e2-micro | 2 vCPU(共享),1GB RAM | 符合免费层条件 | Docker 构建常因 OOM 失败(退出 137) |
**CLI:**
```bash
gcloud compute instances create openclaw-gateway \
--zone=us-central1-a \
--machine-type=e2-small \
--boot-disk-size=20GB \
--image-family=debian-12 \
--image-project=debian-cloud
```
**Console:**
1. 前往 Compute Engine > VM instances > Create instance
2. 名称:`openclaw-gateway`
3. 区域:`us-central1`,可用区:`us-central1-a`
4. 机器类型:`e2-small`
5. 启动磁盘:Debian 12,20GB
6. 创建
CLI:
```bash
gcloud compute ssh openclaw-gateway --zone=us-central1-a
```
**Console:**
在 Compute Engine 控制台中点击你的 VM 旁边的 “SSH” 按钮。
注意:创建 VM 后,SSH 密钥传播可能需要 1-2 分钟。如果连接被拒绝,请等待后重试。
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
```
bash
git clone https://github.com/openclaw/openclaw.git
cd openclaw
本指南假设你将构建自定义镜像,以保证二进制文件持久存在。
Docker 容器是临时的。
所有长期状态都必须保存在主机上。
```bash
mkdir -p ~/.openclaw
mkdir -p ~/.openclaw/workspace
```
在仓库根目录创建 .env。
```bash
OPENCLAW_IMAGE=openclaw:latest
OPENCLAW_GATEWAY_TOKEN=
OPENCLAW_GATEWAY_BIND=lan
OPENCLAW_GATEWAY_PORT=18789
OPENCLAW_CONFIG_DIR=/home/$USER/.openclaw
OPENCLAW_WORKSPACE_DIR=/home/$USER/.openclaw/workspace
GOG_KEYRING_PASSWORD=
XDG_CONFIG_HOME=/home/node/.openclaw
```
如果你想通过 `.env` 管理稳定的网关令牌,请设置 `OPENCLAW_GATEWAY_TOKEN`;
否则请在依赖客户端跨重启连接之前配置 `gateway.auth.token`。
如果两个来源都不存在,OpenClaw 会为该次启动使用仅运行时有效的令牌。
生成一个 keyring 密码并粘贴到 `GOG_KEYRING_PASSWORD`:
```bash
openssl rand -hex 32
```
**不要提交此文件。**
此 `.env` 文件用于容器/运行时环境变量,例如 `OPENCLAW_GATEWAY_TOKEN`。
已存储的提供商 OAuth/API key 认证位于挂载的
`~/.openclaw/agents/<agentId>/agent/auth-profiles.json`。
创建或更新 docker-compose.yml。
```yaml
services:
openclaw-gateway:
image: ${OPENCLAW_IMAGE}
build: .
restart: unless-stopped
env_file:
- .env
environment:
- HOME=/home/node
- NODE_ENV=production
- TERM=xterm-256color
- OPENCLAW_GATEWAY_BIND=${OPENCLAW_GATEWAY_BIND}
- OPENCLAW_GATEWAY_PORT=${OPENCLAW_GATEWAY_PORT}
- OPENCLAW_GATEWAY_TOKEN=${OPENCLAW_GATEWAY_TOKEN}
- GOG_KEYRING_PASSWORD=${GOG_KEYRING_PASSWORD}
- XDG_CONFIG_HOME=${XDG_CONFIG_HOME}
- PATH=/home/linuxbrew/.linuxbrew/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
volumes:
- ${OPENCLAW_CONFIG_DIR}:/home/node/.openclaw
- ${OPENCLAW_WORKSPACE_DIR}:/home/node/.openclaw/workspace
ports:
# 推荐:让 Gateway 网关在 VM 上仅监听 loopback;通过 SSH 隧道访问。
# 如需公开暴露,请移除 `127.0.0.1:` 前缀并相应配置防火墙。
- "127.0.0.1:${OPENCLAW_GATEWAY_PORT}:18789"
command:
[
"node",
"dist/index.js",
"gateway",
"--bind",
"${OPENCLAW_GATEWAY_BIND}",
"--port",
"${OPENCLAW_GATEWAY_PORT}",
"--allow-unconfigured",
]
```
`--allow-unconfigured` 只是为了方便引导启动,并不能替代正确的网关配置。仍需设置认证(`gateway.auth.token` 或密码),并为你的部署使用安全的绑定设置。
使用共享运行时指南完成通用 Docker 主机流程:
- [将所需二进制文件内置到镜像中](/zh-CN/install/docker-vm-runtime#bake-required-binaries-into-the-image)
- [构建并启动](/zh-CN/install/docker-vm-runtime#build-and-launch)
- [哪些内容会持久化到哪里](/zh-CN/install/docker-vm-runtime#what-persists-where)
- [更新](/zh-CN/install/docker-vm-runtime#updates)
在 GCP 上,如果构建在 pnpm install --frozen-lockfile 阶段因 Killed 或 exit code 137 失败,说明 VM 内存不足。最低使用 e2-small,或使用 e2-medium 获得更可靠的首次构建体验。
绑定到 LAN(`OPENCLAW_GATEWAY_BIND=lan`)时,请先配置受信任的浏览器来源再继续:
```bash
docker compose run --rm openclaw-cli config set gateway.controlUi.allowedOrigins '["http://127.0.0.1:18789"]' --strict-json
```
如果你更改了网关端口,请将 `18789` 替换为你配置的端口。
创建 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/`
重新打印一个干净的仪表盘链接:
```bash
docker compose run --rm openclaw-cli dashboard --no-open
```
如果 UI 提示进行共享密钥认证,请将已配置的令牌或密码粘贴到控制 UI 设置中。
此 Docker 流程默认会写入令牌;如果你将容器配置切换为密码认证,请改用该密码。
如果控制 UI 显示 `unauthorized` 或 `disconnected (1008): pairing required`,请批准浏览器设备:
```bash
docker compose run --rm openclaw-cli devices list
docker compose run --rm openclaw-cli devices approve <requestId>
```
还需要再次查看共享持久化和更新参考?
请参见 [Docker VM 运行时](/zh-CN/install/docker-vm-runtime#what-persists-where) 和 [Docker VM 运行时更新](/zh-CN/install/docker-vm-runtime#updates)。
故障排除
SSH 连接被拒绝
创建 VM 后,SSH 密钥传播可能需要 1-2 分钟。等待后重试。
OS Login 问题
检查你的 OS Login 配置文件:
gcloud compute os-login describe-profile
确保你的账号具备所需的 IAM 权限(Compute OS Login 或 Compute OS Admin Login)。
内存不足(OOM)
如果 Docker 构建因 Killed 和 exit code 137 失败,说明 VM 被 OOM 终止了。升级到 e2-small(最低配置)或 e2-medium(推荐用于可靠的本地构建):
# Stop the VM first
gcloud compute instances stop openclaw-gateway --zone=us-central1-a
# Change machine type
gcloud compute instances set-machine-type openclaw-gateway \
--zone=us-central1-a \
--machine-type=e2-small
# Start the VM
gcloud compute instances start openclaw-gateway --zone=us-central1-a
服务账号(安全最佳实践)
个人使用时,你的默认用户账号就足够了。
对于自动化或 CI/CD 流水线,请创建一个具有最小权限的专用服务账号:
- 创建服务账号:
bash
gcloud iam service-accounts create openclaw-deploy \
--display-name="OpenClaw Deployment"
- 授予 Compute Instance Admin 角色(或范围更窄的自定义角色):
bash
gcloud projects add-iam-policy-binding my-openclaw-project \
--member="serviceAccount:openclaw-deploy@my-openclaw-project.iam.gserviceaccount.com" \
--role="roles/compute.instanceAdmin.v1"
避免为自动化使用 Owner 角色。遵循最小权限原则。
IAM 角色详情请参见 https://cloud.google.com/iam/docs/understanding-roles。
后续步骤
- 设置消息渠道:渠道
- 将本地设备配对为节点:节点
- 配置 Gateway 网关:Gateway 网关配置
相关内容
📄 macOS 虚拟机
原文:https://docs.openclaw.ai/zh-CN/install/macos-vm
推荐默认方案(大多数用户)
- 小型 Linux VPS,用于始终在线的 Gateway 网关和低成本。参见 VPS 托管。
- 如果你想要完全控制,并且需要用于浏览器自动化的住宅 IP,使用专用硬件(Mac mini 或 Linux 机器)。许多网站会阻止数据中心 IP,因此本地浏览通常效果更好。
- 混合模式: 将 Gateway 网关放在便宜的 VPS 上,并在需要浏览器/UI 自动化时将你的 Mac 作为节点连接。参见 节点 和 Gateway 网关远程访问。
当你明确需要仅限 macOS 的能力(例如 iMessage),或希望与你日常使用的 Mac 严格隔离时,使用 macOS VM。
macOS VM 选项
在你的 Apple Silicon Mac 上运行本地 VM(Lume)
使用 Lume,在你现有的 Apple Silicon Mac 上的沙箱隔离 macOS VM 中运行 OpenClaw。
这会提供:
- 隔离的完整 macOS 环境(你的宿主机保持干净)
- 通过
imsg支持 iMessage(默认本地路径在 Linux/Windows 上不可用) - 通过克隆 VM 实现即时重置
- 无需额外硬件或云成本
托管 Mac 提供商(云)
如果你想在云端使用 macOS,托管 Mac 提供商也可以:
- MacStadium(托管 Mac)
- 其他托管 Mac 厂商也可使用;遵循它们的 VM + SSH 文档
一旦你获得 macOS VM 的 SSH 访问权限,请继续执行下面的第 6 步。
快速路径(Lume,适合有经验的用户)
- 安装 Lume
lume create openclaw --os macos --ipsw latest- 完成设置助理,启用远程登录(SSH)
lume run openclaw --no-display- SSH 进入,安装 OpenClaw,配置渠道
- 完成
你需要准备什么(Lume)
- Apple Silicon Mac(M1/M2/M3/M4)
- 宿主机运行 macOS Sequoia 或更高版本
- 每个 VM 约 60 GB 可用磁盘空间
- 约 20 分钟
1) 安装 Lume
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)"
如果 ~/.local/bin 不在你的 PATH 中:
echo 'export PATH="$PATH:$HOME/.local/bin"' >> ~/.zshrc && source ~/.zshrc
验证:
lume --version
文档:Lume 安装
2) 创建 macOS VM
lume create openclaw --os macos --ipsw latest
这会下载 macOS 并创建 VM。VNC 窗口会自动打开。
下载可能需要一些时间,具体取决于你的网络连接。
3) 完成设置助理
在 VNC 窗口中:
- 选择语言和地区
- 跳过 Apple ID(如果你之后想使用 iMessage,也可以登录)
- 创建用户账号(记住用户名和密码)
- 跳过所有可选功能
设置完成后,启用 SSH:
- 打开系统设置 → 通用 → 共享
- 启用“远程登录”
4) 获取 VM IP 地址
lume get openclaw
查找 IP 地址(通常是 192.168.64.x)。
5) SSH 进入 VM
ssh youruser@192.168.64.X
将 youruser 替换为你创建的账号,并将 IP 替换为你的 VM IP。
6) 安装 OpenClaw
在 VM 内:
npm install -g openclaw@latest
openclaw onboard --install-daemon
按照新手引导提示设置你的模型提供商(Anthropic、OpenAI 等)。
7) 配置渠道
编辑配置文件:
nano ~/.openclaw/openclaw.json
添加你的渠道:
{
channels: {
whatsapp: {
dmPolicy: "allowlist",
allowFrom: ["+15551234567"],
},
telegram: {
botToken: "YOUR_BOT_TOKEN",
},
},
}
然后登录 WhatsApp(扫描二维码):
openclaw channels login
8) 以无头模式运行 VM
停止 VM 并在无显示模式下重启:
lume stop openclaw
lume run openclaw --no-display
VM 会在后台运行。OpenClaw 的守护进程会保持 Gateway 网关运行。
检查状态:
ssh youruser@192.168.64.X "openclaw status"
额外内容:iMessage 集成
这是在 macOS 上运行的杀手级功能。使用 iMessage 和 imsg 将“信息”加入 OpenClaw。
在 VM 内:
- 登录“信息”。
- 安装
imsg。 - 为运行 OpenClaw/
imsg的进程授予完全磁盘访问权限和自动化权限。 - 使用
imsg rpc --help验证 RPC 支持。
添加到你的 OpenClaw 配置:
{
channels: {
imessage: {
enabled: true,
cliPath: "imsg",
dbPath: "~/Library/Messages/chat.db",
},
},
}
重启 Gateway 网关。现在你的智能体可以发送和接收 iMessage。
完整设置详情:iMessage 渠道
保存黄金镜像
在进一步自定义之前,快照你的干净状态:
lume stop openclaw
lume clone openclaw openclaw-golden
随时重置:
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 托管。
故障排除
| 问题 | 解决方案 |
|---|---|
| 无法 SSH 进入 VM | 检查 VM 的系统设置中是否已启用“远程登录” |
| VM IP 未显示 | 等待 VM 完全启动,然后再次运行 lume get openclaw |
| 找不到 Lume 命令 | 将 ~/.local/bin 添加到你的 PATH |
| WhatsApp 二维码无法扫描 | 运行 openclaw channels login 时,确保你已登录到 VM(而不是宿主机) |
相关文档
- VPS 托管
- 节点
- Gateway 网关远程访问
- iMessage 渠道
- Lume 快速开始
- Lume CLI 参考
- 无人值守 VM 设置(高级)
- Docker 沙箱隔离(替代隔离方案)
📄 exe.dev
原文:https://docs.openclaw.ai/zh-CN/install/exe-dev
目标:OpenClaw Gateway 网关在 exe.dev VM 上运行,并可从你的笔记本电脑通过以下地址访问:https://<vm-name>.exe.xyz
本页假设使用 exe.dev 默认的 exeuntu 镜像。如果你选择了其他发行版,请相应映射软件包。
初学者快速路径
- https://exe.new/openclaw
- 按需填写你的认证密钥/token
- 点击 VM 旁边的“智能体”,并等待 Shelley 完成预配
- 打开
https://<vm-name>.exe.xyz/,并使用配置的共享密钥进行认证(本指南默认使用 token 认证,但如果你切换gateway.auth.mode,密码认证也可用) - 使用
openclaw devices approve <requestId>批准任何待处理的设备配对请求
你需要准备
- exe.dev 账户
- 对 exe.dev 虚拟机的
ssh exe.dev访问权限(可选)
使用 Shelley 自动安装
Shelley 是 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 devices 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
从你的设备运行:
ssh exe.dev new
然后连接:
ssh <vm-name>.exe.xyz
保持这个 VM 有状态。OpenClaw 会将 openclaw.json、每个智能体的 auth-profiles.json、会话以及渠道/提供商状态存储在 ~/.openclaw/ 下,并将工作区存储在 ~/.openclaw/workspace/ 下。
2) 安装前置依赖(在 VM 上)
sudo apt-get update
sudo apt-get install -y git curl jq ca-certificates openssl
3) 安装 OpenClaw
运行 OpenClaw 安装脚本:
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 support
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
# Standard proxy headers
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header X-Forwarded-Proto $scheme;
# Timeout settings for long-lived connections
proxy_read_timeout 86400s;
proxy_send_timeout 86400s;
}
}
覆盖转发标头,而不是保留客户端提供的链。
OpenClaw 只信任来自显式配置代理的转发 IP 元数据,
而追加式 X-Forwarded-For 链会被视为强化安全风险。
5) 访问 OpenClaw 并授予权限
访问 https://<vm-name>.exe.xyz/(参见新手引导中的 Control UI 输出)。如果它提示认证,请粘贴来自 VM 的已配置共享密钥。本指南使用 token 认证,因此使用 openclaw config get gateway.auth.token 获取 gateway.auth.token(或使用 openclaw doctor --generate-gateway-token 生成一个)。
如果你已将 Gateway 网关改为密码认证,请改用 gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD。
使用 openclaw devices list 和 openclaw devices approve <requestId> 批准设备。不确定时,就从浏览器使用 Shelley!
远程渠道设置
对于远程主机,优先使用一次 config patch 调用,而不是多次 SSH 调用 config set。将真实 token 保存在 VM 环境或 ~/.openclaw/.env 中,并且只在 openclaw.json 中放置 SecretRefs。
在 VM 上,让服务环境包含它所需的机密:
cat >> ~/.openclaw/.env <<'EOF'
SLACK_BOT_TOKEN=xoxb-...
SLACK_APP_TOKEN=xapp-...
DISCORD_BOT_TOKEN=...
OPENAI_API_KEY=sk-...
EOF
从你的本地机器创建补丁文件,并将其通过管道传给 VM:
// openclaw.remote.patch.json5
{
secrets: {
providers: {
default: { source: "env" },
},
},
channels: {
slack: {
enabled: true,
mode: "socket",
botToken: { source: "env", provider: "default", id: "SLACK_BOT_TOKEN" },
appToken: { source: "env", provider: "default", id: "SLACK_APP_TOKEN" },
groupPolicy: "open",
requireMention: false,
},
discord: {
enabled: true,
token: { source: "env", provider: "default", id: "DISCORD_BOT_TOKEN" },
dmPolicy: "disabled",
dm: { enabled: false },
groupPolicy: "allowlist",
},
},
agents: {
defaults: {
model: { primary: "openai/gpt-5.5" },
models: {
"openai/gpt-5.5": { params: { fastMode: true } },
},
},
},
}
ssh <vm-name>.exe.xyz 'openclaw config patch --stdin --dry-run' < ./openclaw.remote.patch.json5
ssh <vm-name>.exe.xyz 'openclaw config patch --stdin' < ./openclaw.remote.patch.json5
ssh <vm-name>.exe.xyz 'openclaw gateway restart && openclaw health'
当嵌套允许列表应当精确变为补丁值时,使用 --replace-path,例如替换 Discord 渠道允许列表时:
ssh <vm-name>.exe.xyz 'openclaw config patch --stdin --replace-path "channels.discord.guilds[\"123\"].channels"' < ./discord.patch.json5
远程访问
远程访问由 exe.dev 的认证处理。默认情况下,来自端口 8000 的 HTTP 流量会通过电子邮件认证转发到 https://<vm-name>.exe.xyz。
更新
npm i -g openclaw@latest
openclaw doctor
openclaw gateway restart
openclaw health
指南:更新
相关内容
📄 Railway
原文:https://docs.openclaw.ai/zh-CN/install/railway
Railway
通过一键模板在 Railway 上部署 OpenClaw,并通过网页 Control UI 访问它。
这是最简单的“服务器上无需终端”路径:Railway 会为你运行 Gateway 网关。
快速检查清单(新用户)
- 点击在 Railway 上部署(见下方)。
- 添加一个挂载到
/data的 Volume。 - 设置所需的变量(至少包括
OPENCLAW_GATEWAY_PORT和OPENCLAW_GATEWAY_TOKEN)。 - 在端口
8080上启用 HTTP Proxy。 - 打开
https://<your-railway-domain>/openclaw,并使用已配置的共享密钥连接。此模板默认使用OPENCLAW_GATEWAY_TOKEN;如果你将其替换为密码认证,请改用该密码。
一键部署
部署后,在 Railway → 你的服务 → Settings → Domains 中找到你的公开 URL。
Railway 会:
- 提供一个自动生成的域名(通常为
https://<something>.up.railway.app),或 - 如果你已绑定自定义域名,则使用你的自定义域名。
然后打开:
https://<your-railway-domain>/openclaw— Control UI
你将获得
- 托管的 OpenClaw Gateway 网关 + Control UI
- 通过 Railway Volume(
/data)提供的持久化存储,因此openclaw.json、
每个智能体的auth-profiles.json、渠道/提供商状态、会话以及
工作区都能在重新部署后继续保留
必需的 Railway 设置
公共网络
为该服务启用 HTTP Proxy。
- 端口:
8080
Volume(必需)
挂载一个卷到:
/data
变量
在该服务上设置以下变量:
OPENCLAW_GATEWAY_PORT=8080(必需——必须与公共网络中的端口一致)OPENCLAW_GATEWAY_TOKEN(必需;请将其视为管理员密钥)OPENCLAW_STATE_DIR=/data/.openclaw(推荐)OPENCLAW_WORKSPACE_DIR=/data/workspace(推荐)
连接一个渠道
使用位于 /openclaw 的 Control UI,或通过 Railway 的 shell 运行 openclaw onboard 获取渠道设置说明:
备份与迁移
导出你的状态、配置、认证配置文件和工作区:
openclaw backup create
这会创建一个可移植的备份归档,其中包含 OpenClaw 状态以及任何已配置的
工作区。详情请参见 Backup。
后续步骤
- 设置消息渠道:Channels
- 配置 Gateway 网关:Gateway configuration
- 让 OpenClaw 保持最新:Updating
📄 Render
原文:https://docs.openclaw.ai/zh-CN/install/render
Render
使用基础设施即代码在 Render 上部署 OpenClaw。随附的 render.yaml Blueprint 会以声明式方式定义你的整个技术栈——服务、磁盘、环境变量——因此你可以一键部署,并让基础设施与代码一起进行版本管理。
先决条件
使用 Render Blueprint 部署
点击此链接将会:
- 从此仓库根目录中的
render.yamlBlueprint 创建一个新的 Render 服务。 - 构建 Docker 镜像并部署
部署完成后,你的服务 URL 将遵循 https://<service-name>.onrender.com 这样的格式。
理解 Blueprint
Render Blueprints 是用于定义基础设施的 YAML 文件。此仓库中的 render.yaml 配置了运行 OpenClaw 所需的一切:
services:
- type: web
name: openclaw
runtime: docker
plan: starter
healthCheckPath: /health
envVars:
- key: OPENCLAW_GATEWAY_PORT
value: "8080"
- 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,并在实例不健康时重启 |
generateValue: true |
自动生成加密安全的值 |
disk |
可在重新部署后保留的持久化存储 |
选择套餐
| 套餐 | 休眠 | 磁盘 | 最适合 |
|---|---|---|---|
| Free | 空闲 15 分钟后 | 不可用 | 测试、演示 |
| Starter | 永不 | 1GB+ | 个人使用、小型团队 |
| Standard+ | 永不 | 1GB+ | 生产环境、多个渠道 |
Blueprint 默认使用 starter。若要使用免费层,请在你 fork 的 render.yaml 中将 plan: starter 改为 plan: free(但请注意:没有持久化磁盘意味着 OpenClaw 状态会在每次部署时重置)。
部署之后
访问控制 UI
Web 控制面板位于 https://<your-service>.onrender.com/。
使用已配置的共享密钥进行连接。此部署模板会自动生成 OPENCLAW_GATEWAY_TOKEN(可在 Dashboard → your service → Environment 中找到);如果你将其替换为密码认证,请改用该密码。
Render 控制面板功能
日志
可在 Dashboard → your service → Logs 中查看实时日志。可按以下类型筛选:
- 构建日志(Docker 镜像创建)
- 部署日志(服务启动)
- 运行时日志(应用输出)
Shell 访问
如需调试,可通过 Dashboard → your service → Shell 打开一个 shell 会话。持久化磁盘挂载在 /data。
环境变量
可在 Dashboard → your service → Environment 中修改变量。修改后会触发自动重新部署。
自动部署
如果你使用的是原始 OpenClaw 仓库,Render 不会自动部署你的 OpenClaw。要更新它,请从控制面板手动执行 Blueprint 同步。
自定义域名
- 前往 Dashboard → your service → Settings → Custom Domains
- 添加你的域名
- 按照说明配置 DNS(CNAME 指向
*.onrender.com) - Render 会自动配置 TLS 证书
扩缩容
Render 支持水平扩展和垂直扩展:
- 垂直扩展:更换套餐以获得更多 CPU / RAM
- 水平扩展:增加实例数量(Standard 套餐及以上)
对于 OpenClaw,通常垂直扩展就足够了。水平扩展则需要粘性会话或外部状态管理。
备份与迁移
你可以随时使用 Render 控制面板中的 shell 访问导出状态、配置、认证配置文件和工作区:
openclaw backup create
这会创建一个可移植的备份归档,其中包含 OpenClaw 状态以及所有已配置的工作区。详见备份。
故障排除
服务无法启动
请检查 Render 控制面板中的部署日志。常见问题包括:
- 缺少
OPENCLAW_GATEWAY_TOKEN—— 确认已在 Dashboard → Environment 中设置 - 端口不匹配 —— 确保已设置
OPENCLAW_GATEWAY_PORT=8080,使 Gateway 网关绑定到 Render 所期望的端口
冷启动较慢(免费层)
免费层服务会在空闲 15 分钟后休眠。休眠后的首次请求需要几秒钟,因为容器需要启动。升级到 Starter 套餐即可保持始终在线。
重新部署后数据丢失
这会发生在免费层(无持久化磁盘)上。请升级到付费套餐,或定期在 Render shell 中通过 openclaw backup create 导出完整备份。
健康检查失败
Render 要求 /health 在 30 秒内返回 200 响应。如果构建成功但部署失败,可能是服务启动耗时过长。请检查:
- 构建日志中是否有错误
- 容器在本地使用
docker build && docker run是否可以运行
后续步骤
- 设置消息渠道:Channels
- 配置 Gateway 网关:Gateway 网关配置
- 保持 OpenClaw 为最新版本:更新
📄 Northflank
原文:https://docs.openclaw.ai/zh-CN/install/northflank
Northflank
通过一键模板在 Northflank 上部署 OpenClaw,并通过网页 Control UI 访问它。
这是最简单的“服务器上无需终端”路径:Northflank 会为你运行 Gateway 网关。
如何开始
- 点击 部署 OpenClaw 打开模板。
- 如果你还没有账号,请先在 Northflank 注册账号。
- 点击 立即部署 OpenClaw。
- 设置必需的环境变量:
OPENCLAW_GATEWAY_TOKEN(请使用强随机值)。 - 点击 部署堆栈 以构建并运行 OpenClaw 模板。
- 等待部署完成,然后点击 查看资源。
- 打开 OpenClaw 服务。
- 打开公开的 OpenClaw URL,并访问
/openclaw,然后使用已配置的共享密钥连接。此模板默认使用OPENCLAW_GATEWAY_TOKEN;如果你改用密码认证,请改用该密码。
你将获得
- 托管的 OpenClaw Gateway 网关 + Control UI
- 通过 Northflank Volume(
/data)提供的持久化存储,因此openclaw.json、
每个智能体的auth-profiles.json、渠道/提供商状态、会话以及
工作区都能在重新部署后保留
连接一个渠道
使用 /openclaw 下的 Control UI,或通过 SSH 运行 openclaw onboard 获取渠道设置说明:
后续步骤
- 设置消息渠道:Channels
- 配置 Gateway 网关:Gateway 配置
- 保持 OpenClaw 为最新版本:更新