Fly.io 部署指南

目标： 在 Fly.io 上运行 OpenClaw Gateway，实现持久化存储、自动 HTTPS，并接入 Discord 等消息渠道。

准备工作

安装 flyctl CLI
Fly.io 账号（免费套餐即可起步）
模型 API Key（Anthropic、OpenAI 等）
渠道凭证（Discord Bot Token、Telegram Token 等）

快速上手路径

克隆仓库 → 修改 fly.toml
创建应用 + 挂载卷 → 设置 Secrets
fly deploy 部署
SSH 进容器创建配置文件，或使用 Control UI

创建 Fly 应用

bash

# 克隆仓库
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# 创建 Fly 应用（改成你自己的名字）
fly apps create my-openclaw

# 创建持久化卷（1GB 通常够用）
fly volumes create openclaw_data --size 1 --region iad

提示： 选择离你最近的区域。常用选项：lhr（伦敦）、iad（弗吉尼亚）、sjc（圣何塞）。

配置 fly.toml

修改 fly.toml，填入你的应用名和需要的参数。

安全提示： 默认配置会暴露公网 URL。如需隐藏部署，参考私有部署或使用 fly.private.toml。

toml

app = "my-openclaw"  # 你的应用名
primary_region = "iad"

[build]
  dockerfile = "Dockerfile"

[env]
  NODE_ENV = "production"
  OPENCLAW_PREFER_PNPM = "1"
  OPENCLAW_STATE_DIR = "/data"
  NODE_OPTIONS = "--max-old-space-size=1536"

[processes]
  app = "node dist/index.js gateway --allow-unconfigured --port 3000 --bind lan"

[http_service]
  internal_port = 3000
  force_https = true
  auto_stop_machines = false
  auto_start_machines = true
  min_machines_running = 1
  processes = ["app"]

[[vm]]
  size = "shared-cpu-2x"
  memory = "2048mb"

[mounts]
  source = "openclaw_data"
  destination = "/data"

关键配置说明：

配置项	说明
`--bind lan`	绑定到 `0.0.0.0`，让 Fly 代理能访问 Gateway
`--allow-unconfigured`	无配置文件时也能启动（启动后再创建）
`internal_port = 3000`	必须与 `--port 3000`（或 `OPENCLAW_GATEWAY_PORT`）一致，用于健康检查
`memory = "2048mb"`	512MB 太小；推荐 2GB
`OPENCLAW_STATE_DIR = "/data"`	把状态持久化到挂载卷

设置 Secrets

bash

# 必须：Gateway Token（非 loopback 绑定时需要）
fly secrets set OPENCLAW_GATEWAY_TOKEN=$(openssl rand -hex 32)

# 模型 API Key
fly secrets set ANTHROPIC_API_KEY=sk-ant-...

# 可选：其他模型提供商
fly secrets set OPENAI_API_KEY=sk-...
fly secrets set GOOGLE_API_KEY=...

# 渠道 Token
fly secrets set DISCORD_BOT_TOKEN=MTQ...

注意：
非 loopback 绑定（--bind lan）必须设置 OPENCLAW_GATEWAY_TOKEN。
把这些 Token 当密码一样保管。
优先用环境变量存储 API Key，不要写到 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-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": {}
}
EOF

说明： 设置了 OPENCLAW_STATE_DIR=/data 后，配置路径为 /data/openclaw.json。

Discord Token 可以通过以下两种方式提供：

环境变量：DISCORD_BOT_TOKEN（推荐，避免写入配置文件）
配置文件：channels.discord.token

重启使配置生效：

bash

exit
fly machine restart <machine-id>

访问 Gateway

Control UI

用浏览器打开：

bash

fly open

或直接访问 https://my-openclaw.fly.dev/

粘贴 OPENCLAW_GATEWAY_TOKEN 中的 Token 完成认证。

日志

bash

fly logs              # 实时日志
fly logs --no-tail    # 近期日志

SSH 控制台

bash

fly ssh console

故障排查

"App is not listening on expected address"

Gateway 绑定到了 127.0.0.1 而不是 0.0.0.0。

解决： 在 fly.toml 的进程命令中加上 --bind lan。

健康检查失败 / 连接拒绝

Fly 无法通过配置的端口访问 Gateway。

解决： 确认 internal_port 与 Gateway 端口一致（设置 --port 3000 或 OPENCLAW_GATEWAY_PORT=3000）。

OOM / 内存不足

容器不断重启或被 kill。症状：SIGABRT、v8::internal::Runtime_AllocateInYoungGeneration 或静默重启。

解决： 在 fly.toml 中增加内存：

toml

[[vm]]
  memory = "2048mb"

或更新已有机器：

bash

fly machine update <machine-id> --vm-memory 2048 -y

注意： 512MB 太小。1GB 可以跑，但负载高或日志量大时会 OOM。推荐 2GB。

Gateway 锁文件问题

Gateway 拒绝启动，提示"already running"。

容器重启后 PID 锁文件残留在卷上时会出现此问题。

解决： 删除锁文件：

bash

fly ssh console --command "rm -f /data/gateway.*.lock"
fly machine restart <machine-id>

锁文件位于 /data/gateway.*.lock（不在子目录中）。

配置文件未被读取

使用 --allow-unconfigured 时，Gateway 会创建一个最小配置。重启后应读取你在 /data/openclaw.json 中的自定义配置。

验证配置是否存在：

bash

fly ssh console --command "cat /data/openclaw.json"

通过 SSH 写入配置

fly ssh console -C 不支持 Shell 重定向。写配置文件的方法：

bash

# 用 echo + tee（从本地管道传到远端）
echo '{"your":"config"}' | fly ssh console -C "tee /data/openclaw.json"

# 或用 sftp
fly sftp shell
> put /local/path/config.json /data/openclaw.json

注意： 文件已存在时 fly sftp 可能失败，先删除再传：

bash

fly ssh console --command "rm /data/openclaw.json"

状态未持久化

重启后凭证或 Session 丢失，说明状态目录写到了容器文件系统。

解决： 确认 fly.toml 中设置了 OPENCLAW_STATE_DIR=/data 并重新部署。

更新

bash

# 拉取最新代码
git pull

# 重新部署
fly deploy

# 检查健康状态
fly status
fly logs

更新机器启动命令

如需在不完整重新部署的情况下修改启动命令：

bash

# 获取机器 ID
fly machines list

# 更新命令
fly machine update <machine-id> --command "node dist/index.js gateway --port 3000 --bind lan" -y

# 或同时增加内存
fly machine update <machine-id> --vm-memory 2048 --command "node dist/index.js gateway --port 3000 --bind lan" -y

注意： fly deploy 后机器命令会重置为 fly.toml 中的配置。如果手动做了改动，部署后需重新应用。

私有部署（Hardened）

默认情况下，Fly 会分配公网 IP，让你的龙虾通过 https://your-app.fly.dev 公开访问。这很方便，但也会被网络扫描器（Shodan、Censys 等）发现。

如果想让部署完全不暴露公网，使用私有模板。

何时使用私有部署

你只需要出站消息（无入站 Webhook）
使用 ngrok 或 Tailscale 隧道处理 Webhook 回调
通过 SSH、代理或 WireGuard 访问 Gateway（不用浏览器）
想让部署对互联网扫描器不可见

设置方法

使用 fly.private.toml 替代标准配置：

bash

# 使用私有配置部署
fly deploy -c fly.private.toml

或将已有部署转换为私有：

bash

# 查看当前 IP 列表
fly ips list -a my-openclaw

# 释放公网 IP
fly ips release <public-ipv4> -a my-openclaw
fly ips release <public-ipv6> -a my-openclaw

# 切换为私有配置（后续部署不再分配公网 IP）
fly deploy -c fly.private.toml

# 分配私有 IPv6
fly ips allocate-v6 --private -a my-openclaw

完成后 fly ips list 应只显示 private 类型 IP：

VERSION  IP                   TYPE             REGION
v6       fdaa:x:x:x:x::x      private          global

访问私有部署

没有公网 URL，用以下方法之一访问：

方式一：本地代理（最简单）

bash

# 将本地 3000 端口转发到应用
fly proxy 3000:3000 -a my-openclaw

# 然后在浏览器打开 http://localhost:3000

方式二：WireGuard VPN

bash

# 创建 WireGuard 配置（一次性操作）
fly wireguard create

# 导入到 WireGuard 客户端，然后通过内部 IPv6 访问
# 例如：http://[fdaa:x:x:x:x::x]:3000

方式三：仅 SSH

bash

fly ssh console -a my-openclaw

私有部署下的 Webhook

如需 Webhook 回调（Twilio、Telnyx 等）又不暴露公网：

ngrok 隧道 — 在容器内或旁路运行 ngrok
Tailscale Funnel — 通过 Tailscale 暴露特定路径
仅出站 — 某些服务商（如 Twilio）纯出站也能工作，不需要 Webhook

带 ngrok 的语音通话配置示例：

json5

{
  plugins: {
    entries: {
      "voice-call": {
        enabled: true,
        config: {
          provider: "twilio",
          tunnel: { provider: "ngrok" },
          webhookSecurity: {
            allowedHosts: ["example.ngrok.app"],
          },
        },
      },
    },
  },
}

ngrok 隧道在容器内运行，提供公网 Webhook URL，而不暴露 Fly 应用本身。将 webhookSecurity.allowedHosts 设为隧道的公网主机名。

安全对比

方面	公开部署	私有部署
互联网扫描器	可发现	隐藏
直接攻击	可能	阻断
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 定价页面。

下一步

配置消息渠道：Channels
配置 Gateway：Gateway 配置
保持 OpenClaw 更新：更新指南

Fly.io 部署指南 ​

准备工作 ​

快速上手路径 ​

Control UI ​

日志 ​

SSH 控制台 ​

故障排查 ​

"App is not listening on expected address" ​

健康检查失败 / 连接拒绝 ​

OOM / 内存不足 ​

Gateway 锁文件问题 ​

配置文件未被读取 ​

通过 SSH 写入配置 ​

状态未持久化 ​

更新 ​

更新机器启动命令 ​

私有部署（Hardened） ​

何时使用私有部署 ​

设置方法 ​

访问私有部署 ​

私有部署下的 Webhook ​

安全对比 ​

备注 ​

费用 ​

下一步 ​

Fly.io 部署指南

准备工作

快速上手路径

Control UI

日志

SSH 控制台

故障排查

"App is not listening on expected address"

健康检查失败 / 连接拒绝

OOM / 内存不足

Gateway 锁文件问题

配置文件未被读取

通过 SSH 写入配置

状态未持久化

更新

更新机器启动命令

私有部署（Hardened）

何时使用私有部署

设置方法

访问私有部署

私有部署下的 Webhook

安全对比

备注

费用

下一步