OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Platforms overview

EasyRunner

EasyRunner는 Caddy 프록시 뒤에서 OpenClaw Gateway를 소규모 컨테이너화 앱으로 호스팅합니다. 이 가이드에서는 Podman 호환 Compose 앱을 실행하고 Caddy를 통해 HTTPS를 종료하는 EasyRunner 호스트를 전제로 합니다.

시작하기 전에

  • 도메인이 연결된 EasyRunner 서버
  • 공식 OpenClaw 이미지(ghcr.io/openclaw/openclaw) 또는 자체 빌드
  • /home/node/.openclaw용 영구 구성 볼륨
  • /home/node/.openclaw/workspace용 영구 작업 공간 볼륨
  • 강력한 Gateway 토큰 또는 비밀번호

가능하면 기기 인증을 활성화된 상태로 유지하세요. 리버스 프록시가 기기 ID를 올바르게 전달할 수 없다면 먼저 신뢰할 수 있는 프록시 설정을 수정하세요(신뢰할 수 있는 프록시 인증 참조). 위험한 인증 우회는 운영자가 제어하는 완전한 사설 네트워크에서만 사용하세요.

Compose 앱

다음과 같은 형태의 Compose 파일로 EasyRunner 앱을 생성하세요.

yaml
services:  openclaw:    image: ghcr.io/openclaw/openclaw:latest    restart: unless-stopped    environment:      OPENCLAW_GATEWAY_TOKEN: ${OPENCLAW_GATEWAY_TOKEN}      OPENCLAW_HOME: /home/node      OPENCLAW_STATE_DIR: /home/node/.openclaw      OPENCLAW_CONFIG_PATH: /home/node/.openclaw/openclaw.json      OPENCLAW_WORKSPACE_DIR: /home/node/.openclaw/workspace    volumes:      - openclaw-config:/home/node/.openclaw      - openclaw-workspace:/home/node/.openclaw/workspace    labels:      caddy: openclaw.example.com      caddy.reverse_proxy: "{{upstreams 1455}}"    command: ["node", "openclaw.mjs", "gateway", "--bind", "lan", "--port", "1455"] volumes:  openclaw-config:  openclaw-workspace:

openclaw.example.com을 Gateway 호스트 이름으로 바꾸세요. OPENCLAW_GATEWAY_TOKEN을 앱 정의에 커밋하지 말고 EasyRunner의 비밀 정보/환경 관리자에 저장하세요. 이미지는 기본적으로 local loopback에 바인딩되므로 Caddy가 컨테이너에 접근하려면 command에 명시적인 --bind lan --port 1455가 필요합니다.

OpenClaw 구성

영구 구성 볼륨 내부에서 Gateway에는 프록시를 통해서만 접근할 수 있도록 유지하고 인증을 요구하세요.

json5
{  gateway: {    bind: "lan",    port: 1455,    auth: {      token: "${OPENCLAW_GATEWAY_TOKEN}",    },  },}

Caddy가 Gateway의 TLS를 종료하는 경우 인증 검사를 전역적으로 비활성화하지 말고 정확한 프록시 경로에 맞게 신뢰할 수 있는 프록시 설정을 구성하세요. 신뢰할 수 있는 프록시 인증을 참조하세요.

확인

워크스테이션에서 다음을 실행하세요.

bash
openclaw gateway probe --url https://openclaw.example.com --token <token>openclaw gateway status --url https://openclaw.example.com --token <token>

EasyRunner 호스트에서는 GET /healthz(활성 상태)와 GET /readyz(준비 상태)에 인증이 필요하지 않으며, 이미지에 내장된 컨테이너 상태 확인에 사용됩니다. 또한 앱 로그에서 Gateway가 수신 대기 중인지, 시작 시 SecretRef, Plugin 또는 채널 인증 실패가 없는지 확인하세요.

업데이트 및 백업

  • 새 OpenClaw 이미지를 가져오거나 빌드한 후 EasyRunner 앱을 다시 배포하세요.
  • 업데이트 전에 openclaw-config 볼륨을 백업하세요. 이 볼륨에는 openclaw.json, agents/<agentId>/agent/auth-profiles.json, 설치된 Plugin 패키지 상태가 저장됩니다.
  • 에이전트가 openclaw-workspace에 영구 프로젝트 데이터를 기록하는 경우 해당 볼륨을 백업하세요.
  • 주요 업데이트 후 openclaw doctor를 실행하여 구성 마이그레이션과 서비스 경고를 확인하세요.

문제 해결

  • gateway probe가 연결되지 않음: Caddy 호스트 이름이 앱을 가리키는지, 컨테이너가 0.0.0.0:1455에서 수신 대기하는지 확인하세요.
  • 인증 실패: EasyRunner 비밀 정보와 로컬 클라이언트 명령의 토큰을 함께 교체하세요.
  • 복원 후 파일 소유자가 root로 설정됨: 이미지는 node(uid 1000)로 실행됩니다. 해당 사용자가 /home/node/.openclaw 및 /home/node/.openclaw/workspace에 쓸 수 있도록 마운트된 볼륨의 권한을 수정하세요.
  • 브라우저 또는 채널 Plugin 실패: 필요한 외부 바이너리, 외부 네트워크 연결, 마운트된 자격 증명을 컨테이너 내부에서 사용할 수 있는지 확인하세요.
Was this useful?
On this page

On this page