> ## Documentation Index
> Fetch the complete documentation index at: https://openclawdoc.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Render에 배포하기

> Render Blueprint와 render.yaml을 사용해 OpenClaw를 배포하고 영구 디스크와 설정 wizard를 구성하는 가이드

Infrastructure as Code 방식으로 Render에 OpenClaw를 배포합니다. 함께 제공되는 `render.yaml` Blueprint가 서비스, 디스크, 환경 변수까지 전체 스택을 선언적으로 정의하므로, 한 번의 클릭으로 배포하고 인프라를 코드와 함께 버전 관리할 수 있습니다.

## 준비 사항

* [Render 계정](https://render.com)(무료 티어 가능)
* 원하는 [model provider](/providers)의 API key

## Render Blueprint로 배포

[Deploy to Render](https://render.com/deploy?repo=https://github.com/openclaw/openclaw)

이 링크를 클릭하면 다음이 실행됩니다.

1. 이 저장소 루트의 `render.yaml` Blueprint에서 새 Render 서비스를 만듭니다.
2. `SETUP_PASSWORD` 입력을 요청합니다.
3. Docker 이미지를 빌드하고 배포합니다.

배포가 끝나면 서비스 URL은 `https://<service-name>.onrender.com` 형식입니다.

## Blueprint 이해하기

Render Blueprint는 인프라를 정의하는 YAML 파일입니다. 이 저장소의 `render.yaml`은 OpenClaw 실행에 필요한 모든 구성을 담고 있습니다.

```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}}
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 기능:

| Feature               | Purpose                               |
| --------------------- | ------------------------------------- |
| `runtime: docker`     | 저장소의 Dockerfile로 빌드                   |
| `healthCheckPath`     | Render가 `/health`를 감시하고 비정상 인스턴스를 재시작 |
| `sync: false`         | 배포 중 값 입력 요청(secret)                  |
| `generateValue: true` | 암호학적으로 안전한 값 자동 생성                    |
| `disk`                | 재배포 후에도 유지되는 영구 스토리지                  |

## 플랜 선택

| Plan      | Spin-down | Disk  | Best for     |
| --------- | --------- | ----- | ------------ |
| Free      | 15분 유휴 후  | 사용 불가 | 테스트, 데모      |
| Starter   | 없음        | 1GB+  | 개인 사용, 소규모 팀 |
| Standard+ | 없음        | 1GB+  | 운영 환경, 여러 채널 |

Blueprint 기본값은 `starter`입니다. 무료 티어를 쓰려면 포크한 저장소의 `render.yaml`에서 `plan: free`로 바꾸세요. 단, 영구 디스크가 없어서 배포할 때마다 설정이 초기화됩니다.

## 배포 후

### 설정 wizard 완료

1. `https://<your-service>.onrender.com/setup`으로 이동합니다.
2. `SETUP_PASSWORD`를 입력합니다.
3. model provider를 고르고 API key를 붙여 넣습니다.
4. 필요하면 메시징 채널(Telegram, Discord, Slack)을 설정합니다.
5. **Run setup**을 클릭합니다.

### Control UI 접근

웹 대시보드는 `https://<your-service>.onrender.com/openclaw`에서 열 수 있습니다.

## Render Dashboard 기능

### Logs

실시간 로그는 **Dashboard → your service → Logs**에서 확인합니다. 다음 로그를 구분해 볼 수 있습니다.

* Build logs(Docker 이미지 생성)
* Deploy logs(서비스 시작)
* Runtime logs(애플리케이션 출력)

### Shell access

디버깅용 shell 세션은 **Dashboard → your service → Shell**에서 열 수 있습니다. persistent disk는 `/data`에 마운트됩니다.

### Environment variables

변수 수정은 **Dashboard → your service → Environment**에서 합니다. 변경하면 자동으로 재배포가 트리거됩니다.

### Auto-deploy

원본 OpenClaw 저장소를 그대로 사용하면 Render가 OpenClaw를 자동 배포하지는 않습니다. 업데이트하려면 대시보드에서 수동 Blueprint sync를 실행하세요.

## Custom domain

1. **Dashboard → your service → Settings → Custom Domains**로 이동합니다.
2. 도메인을 추가합니다.
3. 안내에 따라 DNS를 설정합니다(`*.onrender.com`으로 CNAME).
4. Render가 TLS 인증서를 자동 발급합니다.

## 스케일링

Render는 수평/수직 확장을 모두 지원합니다.

* **Vertical**: plan을 올려 CPU/RAM 증설
* **Horizontal**: 인스턴스 수 증가(Standard 이상)

OpenClaw는 보통 수직 확장만으로 충분합니다. 수평 확장에는 sticky session이나 외부 상태 관리가 필요합니다.

## 백업과 마이그레이션

설정과 workspace는 언제든지 내보낼 수 있습니다.

```text theme={"theme":{"light":"min-light","dark":"min-dark"}}
https://<your-service>.onrender.com/setup/export
```

이 주소는 어떤 OpenClaw 호스트에도 복원할 수 있는 portable backup을 내려줍니다.

## 문제 해결

### 서비스가 시작되지 않음

Render Dashboard의 deploy log를 확인하세요. 흔한 원인은 다음과 같습니다.

* `SETUP_PASSWORD` 누락: Blueprint가 입력을 요청하지만 실제로 설정됐는지 확인 필요
* 포트 불일치: `PORT=8080`이 Dockerfile의 노출 포트와 일치하는지 확인

### 느린 cold start(무료 티어)

무료 티어 서비스는 15분 동안 유휴 상태이면 내려갑니다. 그다음 첫 요청은 컨테이너가 뜰 때까지 몇 초 걸릴 수 있습니다. 항상 켜진 환경이 필요하면 Starter plan으로 올리세요.

### 재배포 후 데이터 손실

무료 티어에서 발생합니다. 영구 디스크가 없기 때문입니다. 유료 플랜으로 올리거나 `/setup/export`로 설정을 정기적으로 내보내세요.

### Health check 실패

Render는 `/health`에서 30초 안에 200 응답을 기대합니다. 빌드는 성공했는데 배포가 실패하면 서비스 시작이 너무 오래 걸리는 것일 수 있습니다. 다음을 확인하세요.

* Build log에 오류가 없는지
* `docker build && docker run`으로 로컬에서 컨테이너가 정상 실행되는지