> ## Documentation Index
> Fetch the complete documentation index at: https://clawdbot.openclaw-doc-zh.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 在 Render 部署（Deploy on Render）

使用 Infrastructure as Code 在 Render 上部署 OpenClaw。随附的 `render.yaml` Blueprint 以声明式方式定义整个堆栈（服务、磁盘、环境变量），因此你可以一键部署，并将基础设施与代码一起版本化。

## 前置条件（Prerequisites）

* 一个 [Render 账号](https://render.com)（提供免费档）
* 你偏好的 [模型提供方](/docs/providers) API key

## 用 Render Blueprint 部署（Deploy with a Render Blueprint）

<a href="https://render.com/deploy?repo=https://github.com/openclaw/openclaw" target="_blank" rel="noreferrer">
  Deploy to Render
</a>

点击该链接会：

1. 基于本仓库根目录的 `render.yaml` Blueprint 创建新的 Render 服务。
2. 提示你设置 `SETUP_PASSWORD`
3. 构建 Docker 镜像并部署

部署后，服务 URL 形如 `https://<service-name>.onrender.com`。

## 了解 Blueprint（Understanding the Blueprint）

Render Blueprint 是定义基础设施的 YAML 文件。本仓库的 `render.yaml` 已配置运行 OpenClaw 所需的一切：

```yaml theme={null}
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`                | 持久化存储（重部署后仍保留）               |

## 选择计划（Choosing a plan）

| 计划        | 休眠策略       | 磁盘   | 适用场景     |
| --------- | ---------- | ---- | -------- |
| Free      | 15 分钟闲置后休眠 | 不支持  | 测试、演示    |
| Starter   | 不休眠        | 1GB+ | 个人使用、小团队 |
| Standard+ | 不休眠        | 1GB+ | 生产、多渠道   |

Blueprint 默认 `starter`。如需免费档，请在你的 fork 的 `render.yaml` 中改为 `plan: free`（但注意：无持久化磁盘会导致每次部署重置配置）。

## 部署后（After deployment）

### 完成设置向导（Complete the setup wizard）

1. 打开 `https://<your-service>.onrender.com/setup`
2. 输入 `SETUP_PASSWORD`
3. 选择模型提供方并粘贴 API key
4. （可选）配置消息渠道（Telegram、Discord、Slack）
5. 点击 **Run setup**

### 访问 Control UI（Access the Control UI）

Web 仪表盘地址：`https://<your-service>.onrender.com/openclaw`。

## Render Dashboard 功能（Render Dashboard features）

### 日志（Logs）

在 **Dashboard → your service → Logs** 查看实时日志，可过滤：

* Build logs（Docker 镜像构建）
* Deploy logs（服务启动）
* Runtime logs（应用输出）

### Shell 访问（Shell access）

调试时可通过 **Dashboard → your service → Shell** 打开 shell。持久化磁盘挂载在 `/data`。

### 环境变量（Environment variables）

在 **Dashboard → your service → Environment** 修改变量。变更会触发自动重部署。

### 自动部署（Auto-deploy）

若使用原始 OpenClaw 仓库，Render 不会自动部署你的 OpenClaw。需要更新时，在 Dashboard 手动执行 Blueprint 同步。

## 自定义域名（Custom domain）

1. 打开 **Dashboard → your service → Settings → Custom Domains**
2. 添加域名
3. 按提示配置 DNS（CNAME 指向 `*.onrender.com`）
4. Render 会自动签发 TLS 证书

## 扩容（Scaling）

Render 支持水平与垂直扩容：

* **垂直**：升级计划以获得更多 CPU/RAM
* **水平**：增加实例数量（Standard 及以上）

对 OpenClaw 来说，通常只需垂直扩容。水平扩容需要会话粘性或外部状态管理。

## 备份与迁移（Backups and migration）

随时导出配置与工作区：

```
https://<your-service>.onrender.com/setup/export
```

这会下载一个可移植备份，可在任何 OpenClaw 主机上恢复。

## 故障排查（Troubleshooting）

### 服务无法启动（Service won't start）

查看 Render Dashboard 的部署日志。常见原因：

* 未设置 `SETUP_PASSWORD` — Blueprint 会提示输入，但请确认已设置
* 端口不匹配 — 确保 `PORT=8080` 与 Dockerfile 暴露端口一致

### 冷启动慢（免费档）

免费档服务在 15 分钟无请求后会休眠。首次请求需要几秒来启动容器。若需常驻，升级到 Starter 计划。

### 重部署后数据丢失（Data loss after redeploy）

这通常发生在免费档（无持久化磁盘）。升级付费计划，或定期通过 `/setup/export` 导出配置。

### 健康检查失败（Health check failures）

Render 期望 `/health` 在 30 秒内返回 200。如果构建成功但部署失败，服务可能启动过慢。请检查：

* Build logs 是否报错
* 容器能否在本地通过 `docker build && docker run` 正常运行