Cloudflare Containers
在 Cloudflare Worker 和命名 Durable Object 后面运行一个 OpenClaw 实例,使用官方 OpenClaw 镜像并通过 Litestream 复制到 R2。
Warning
此部署目标为实验性。Litestream 保护的是 SQLite 数据库,而非完整的 OpenClaw 状态目录。在使用生产凭据之前,请阅读限制与恢复。
你需要什么¶
- 一个 Cloudflare 账户,且可使用 Workers、Containers 和 R2
- 支持
linux/amd64的 Docker Buildx - 一个公共 Docker Hub 仓库,用于存放派生镜像,以及一个可向其推送的
docker login会话 - 一个兼容 S3 的 CLI(例如 AWS CLI),稍后用于验证 Litestream 复制
- Node.js 和 npm
- 你的 OpenClaw 设置所需的提供商和渠道凭据
模板位于 scripts/cloudflare。它部署一个 standard-2 Container,并设置 max_instances: 1。
工作原理¶
Worker 将每个 HTTP 和 WebSocket 请求转发到一个固定的 Durable Object 名称。该 Durable Object 拥有一个 Container 实例,并构成围绕 Litestream 副本的单写入围栏。Container 在端口 8080 上公开 OpenClaw,Durable Object 在路由到它之前会轮询 /healthz。
flowchart TD
client[Channels, browsers, API clients]
worker[Cloudflare Worker]
durable[Durable Object, one stable name]
container[Container running the OpenClaw Gateway on 8080]
litestream[Litestream sidecar process]
r2[(R2 bucket of SQLite replicas)]
client --> worker
worker --> durable
durable --> container
container --> litestream
litestream -- continuous WAL streaming --> r2
r2 -- restore on boot --> container
Litestream 监视两个 SQLite 根目录:
/home/node/.openclaw/state/*.sqlite/home/node/.openclaw/agents/**/*.sqlite
在启动时,入口点使用 R2 的 S3 ListObjectsV2 API 作为恢复清单,拒绝这些根目录之外的路径,恢复每个发现的数据库,然后才启动 Gateway。
在此模板上对照真实 R2 bucket 实测:从写入到副本约 2.4 秒;将两个数据库恢复到全新 Container 约 9 秒,该 Container 在启动后约 13 秒达到健康 Gateway。请将这些视为数量级预期,而非保证。
部署¶
1. 准备模板
克隆 OpenClaw 并进入模板目录:
git clone https://github.com/openclaw/openclaw.git
cd openclaw/scripts/cloudflare
npm install
npx wrangler login
npx wrangler whoami
在创建资源之前,确认 Wrangler 已选择预期的 Cloudflare 账户。
2. 创建 R2 存储
创建 bucket:
在 Cloudflare 控制台中,创建一个 R2 API token,其对象读写权限仅限于该 bucket。请勿将访问密钥 ID 和秘密访问密钥包含在 checkout 目录中。
在 wrangler.jsonc 中,替换 endpoint 中的 <account-id>。如果你使用其他 bucket 名称,请同时更新 LITESTREAM_BUCKET 和 r2_buckets[].bucket_name。
R2 绑定用于 Worker 端的访问和文档完整性。Litestream 无法从 Container 内部使用 Worker 绑定;它使用 R2 的 S3 endpoint 以及通过 Worker secrets 传入的凭据。
3. 发布 Container 镜像
将 Dockerfile 中的 <official-openclaw-image-digest> 替换为官方 openclaw/openclaw Docker Hub 仓库中的不可变 digest。
为 Cloudflare 所需的架构构建派生镜像,并将其推送到公共 Docker Hub 仓库:
docker buildx build \
--platform linux/amd64 \
--tag docker.io/<docker-hub-user>/openclaw-cloudflare:<version> \
--push \
.
docker buildx imagetools inspect \
docker.io/<docker-hub-user>/openclaw-cloudflare:<version>
将 wrangler.jsonc 中的 containers[].image 占位符替换为生成的不可变 docker.io/...@sha256:... 引用。Cloudflare Containers 可以直接拉取公共 Docker Hub 镜像;此模板不支持 GHCR 作为来源。
4. 部署 Worker 和 Container
编译 Worker 并部署:
首次部署会创建 Worker、基于 SQLite 的 Durable Object 类、Container 应用和 R2 绑定。
5. 设置运行时 secrets
通过 Wrangler 的 secret 提示添加 R2 和 Gateway 凭据:
npx wrangler secret put LITESTREAM_ACCESS_KEY_ID
npx wrangler secret put LITESTREAM_SECRET_ACCESS_KEY
npx wrangler secret put OPENCLAW_GATEWAY_TOKEN
根据需要添加提供商和渠道变量。例如:
src/container.ts 向 Container 传递一个显式的环境变量允许列表。在使用其他基于环境变量的凭据之前,请先在该文件中添加相应名称。
6. 引导 OpenClaw
首次启动需要在 Container 内进行一次交互式会话。SSH 访问默认处于禁用状态;请在 wrangler.jsonc 的 container 条目中添加以下配置以临时启用,然后重新部署:
打开一次已部署的 Worker URL 以启动实例。然后找到 application 和 instance ID 并连接:
npx wrangler containers list
npx wrangler containers instances <application-id> --json
npx wrangler containers ssh <instance-id>
SSH 由 wrangler 中转,并且仅限于具有容器写入权限的账户。引导完成后,你可以移除 ssh 块并重新部署;恢复的状态会通过 Litestream 在替换后继续保留。
在 Container 内部,运行基于 SecretRef 的设置。此示例使用 OpenAI 和 Telegram:
cd /app
node openclaw.mjs onboard --non-interactive --accept-risk --skip-health \
--mode local \
--auth-choice openai-api-key \
--secret-input-mode ref \
--gateway-auth token \
--gateway-token-ref-env OPENCLAW_GATEWAY_TOKEN \
--skip-channels \
--no-install-daemon
node openclaw.mjs channels add --channel telegram --use-env
node openclaw.mjs doctor --json
将你确切的引导配方保存在一份私有的、可复现的运行手册中。全新的 Container 磁盘不会保留生成的配置。
验证部署¶
在首次引导之后、依赖此部署之前,运行以下检查。
确认 Gateway 能够应答。/healthz 报告监听器已启动。/startupz 额外报告启动工作已完成,同时忽略通道健康状态,因此当某个通道账号损坏时它仍保持绿色;只有由 v2026.8.1 或更新版本构建的镜像才提供该端点:
curl -sS https://<worker-subdomain>.workers.dev/healthz
curl -sS -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
https://<worker-subdomain>.workers.dev/readyz
确认复制确实到达 R2。Litestream 将键写入 replicas/state/<database>/<generation>/ 前缀下,因此请使用你提供给 Litestream 的同一 R2 凭据,通过任何兼容 S3 的客户端列出该前缀。Wrangler 无法列出对象键,只能按精确路径获取它们:
aws s3 ls "s3://openclaw-backups/replicas/" --recursive \
--endpoint-url "https://<account-id>.r2.cloudflarestorage.com"
Cloudflare 控制台的 R2 对象浏览器会显示相同的树结构。经过几分钟活动后前缀仍为空,说明复制未正常工作;请在继续之前修复它。
在需要恢复之前先演练。未经测试的恢复路径不算是备份:
- 发送一条消息,让 Gateway 写入一个会话行。
- 等待约十秒以完成复制。
- 删除 Container 实例,或重新部署以强制替换。
- 重新打开 Worker URL,确认对话仍然存在。
如果步骤 4 丢失了数据,请在连接生产通道之前停止并修复复制。
成本与规格¶
Containers 需要 Workers Paid 计划。只要 Container 处于唤醒状态,内存和磁盘就会按该实例类型预置的资源计费;CPU 仅按实际使用计费。
默认的 standard-2 实例预置 1 vCPU、6 GiB 内存和 12 GB 磁盘。因此,让它整月始终运行,费用主要由预置内存决定,而非取决于 Agent 有多繁忙。按公布的价格计算,在计算出口流量之前,每月大约为 40 至 50 美元,包含计划费用,其中大部分是内存。
这对下面的生命周期决策很重要:
- Socket 通道会让 Container 保持唤醒,因此它们按始终在线费率计费。一台小型常驻虚拟机通常更便宜。选择 Cloudflare 是因为其运维模式、与其他 Cloudflare 服务共置,或 R2 持久化路径,而不是为了省钱。
- 仅 Webhook 的安装会休眠,而休眠的 Container 不产生任何费用。这正是该目标真正便宜的場景。
在最终确定之前,请查看 Cloudflare 的 Containers 定价页面 核对当前费率;这些数字是根据已发布的价目表估算的,并且会在 OpenClaw 之外独立变化。
可观测性¶
在重现问题期间流式查看 Worker 和 Container 日志:
npx wrangler tail
npx wrangler containers list
npx wrangler containers instances <application-id> --json
Gateway 日志保留在 Container 内部。可以通过引导步骤中描述的临时 SSH 会话访问它们,或将它们转发到你自己的收集器。Container 文件系统是临时的,因此请将 Container 内日志视为调试输出,而不是持久记录。
选择生命周期模式¶
OPENCLAW_WEBHOOK_ONLY 默认值为 false,这会使 Container 在空闲期间保持运行。对于维护 socket 或长生命周期进程的通道,请保留此默认值,包括:
- Discord
- Slack Socket Mode
仅当所有已启用的通道都通过 HTTP webhook 接收流量时,才将 OPENCLAW_WEBHOOK_ONLY 设置为 true。在该模式下,Container 会在空闲十分钟后停止,并在下一个请求时冷启动。
Warning
缩容到零会从全新磁盘启动。仅当外部进程可以重新应用你的声明式引导时,才启用此模式。Litestream 可以恢复 SQLite,但无法重新创建 openclaw.json、凭据文件、已安装的插件或工作区。
限制与恢复¶
- 单一写入者: 每个请求都会解析到同一个 Durable Object 名称,Cloudflare 会为该名称运行一个存活的 Durable Object 实例。不要增加
max_instances,也不要引入绕过此限制的替代路由。在平台替换或滚动发布期间,旧/新 Container 短暂重叠是可接受的实验性权衡。 - 恢复点: 一秒的 Litestream 同步间隔通常产生秒级 RPO。它不是同步复制,突然终止可能会丢失尚未到达 R2 的写入。
- 临时磁盘: 每次休眠、替换或主机重启都会从镜像加上已恢复的 SQLite 数据库开始。对于配置、凭据文件、插件文件和工作区,请使用 OpenClaw 完整归档。
- 回滚: 较旧的数据库字节是时间旅行。通道凭据(尤其是 WhatsApp)的棘轮式推进可能导致不同步;审批以及投递/去重状态也会回滚。在恢复之前,请重新关联受影响的通道并审查待处理的审批。请参阅 恢复。
- WebSocket: Worker 和 Container 代理支持 WebSocket。Cloudflare 将每个收到的 WebSocket 消息限制为 32 MiB。
- 出口流量: 出站请求使用共享的 Cloudflare IP 空间。此目标不提供固定出口地址。
- Provider 边界: 这是一个部署模板,不是 OpenClaw 的
cloudWorkersprovider。其运维 SSH 访问不实现该 provider 的 SSH 执行契约。
更新¶
基于新的不可变官方 OpenClaw digest 构建新的派生镜像,推送它,更新 wrangler.jsonc 中的派生 digest,然后部署:
先在单独的 R2 bucket 上测试更新和回滚。在激活较旧的字节之前,请保留当前状态。
故障排查¶
Worker 返回 5xx 且 Container 始终未就绪 —— Cloudflare 只运行从公共 registry 拉取的 linux/amd64 镜像。请使用 --platform linux/amd64 重新构建,确认派生的 Docker Hub 仓库是公共的,并确认 containers[].image 使用已推送的 digest 而不是移动标签。
部署成功但每个请求都超时 -- Container 助手会等待 GET /healthz。请检查 Container 内的 Gateway 是否监听端口 8080,并且没有引导步骤更改了端口。
某项检查通过,但 Gateway 实际上并未提供服务 -- Control UI 会用一个兜底 200 响应未知路径,因此检查一个你的镜像未提供服务的某个路由会看起来始终健康。在信任检查结果之前,请验证响应体是 JSON 而不是 HTML。
Litestream 日志中出现身份验证或签名错误 -- Litestream 需要 R2 S3 API 凭据,它们与 Cloudflare API token 不同。请创建一个 R2 API token,并使用其 access key ID 和 secret access key,同时确认 LITESTREAM_ENDPOINT 包含你的 account ID。
首次启动日志中没有可恢复的数据库 -- 在空存储桶中这是预期行为。入口点会将空的副本列表视为全新安装,并正常启动 Gateway。
/readyz 返回 503,而 /startupz 返回 200 -- 这是按设计工作的。启动已完成,并且某个已配置的 channel 账户不健康。请检查 channel 状态,而不是重启 Container;参见 健康检查。
wrangler containers ssh 被拒绝 -- SSH 默认处于禁用状态。请在容器条目中添加 "ssh": { "enabled": true },重新部署,然后连接。
配置在休眠或重新部署后消失 -- Litestream 只恢复 SQLite 数据库。openclaw.json、凭据文件、已安装的插件文件和工作区位于临时磁盘上。请重新应用你的引导运行手册,或保持安装始终在线并获取 完整归档。
Channel 会话在恢复后中断 -- 恢复较旧的字节会回滚 ratcheting 凭据。请重新链接受影响的 channel,并检查待处理审批;参见 限制与恢复。
WebSocket 连接在大负载时关闭 -- Cloudflare 会关闭大于 32 MiB 的已接收 WebSocket 消息。请减小附件大小,或通过带外方式传输它们。
相关¶
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw