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

Hosting

Hetzner

Docker를 사용하여 Hetzner VPS에서 영구 OpenClaw Gateway를 실행하고, 상태를 영속적으로 보존하며, 필요한 바이너리를 이미지에 내장하고, 안전한 재시작 동작을 구성합니다.

Hetzner 요금은 변경될 수 있습니다. 요구 사항을 충족하는 가장 작은 Debian/Ubuntu VPS를 선택하고 OOM이 발생하면 사양을 높이세요.

노트북에서 SSH 포트 포워딩을 사용해 Gateway에 접근할 수 있습니다. 방화벽과 토큰을 직접 관리하는 경우 포트를 직접 노출할 수도 있습니다.

보안 모델 주의 사항:

  • 모두가 동일한 신뢰 경계에 있고 런타임을 업무 전용으로 사용하는 경우 회사 공유 에이전트를 사용해도 됩니다.
  • 엄격하게 분리하세요. 전용 VPS/런타임과 전용 계정을 사용하고, 해당 호스트에서 개인 Apple/Google/브라우저/비밀번호 관리자 프로필을 사용하지 마세요.
  • 사용자들이 서로를 신뢰할 수 없는 경우 Gateway/호스트/OS 사용자별로 분리하세요.

보안 및 VPS 호스팅을 참조하세요.

이 가이드에서는 Hetzner의 Ubuntu 또는 Debian을 사용한다고 가정합니다. 다른 Linux VPS에서는 그에 맞는 패키지를 사용하세요. 일반적인 Docker 절차는 Docker를 참조하세요.

필요한 항목

  • 루트 접근 권한이 있는 Hetzner VPS
  • 노트북에서의 SSH 접근
  • Docker 및 Docker Compose
  • 모델 인증 자격 증명
  • 선택적 공급자 자격 증명(WhatsApp QR, Telegram 봇 토큰, Gmail OAuth)
  • 약 20분

빠른 절차

  1. Hetzner VPS 프로비저닝
  2. Docker 설치
  3. OpenClaw 저장소 복제
  4. 영구 호스트 디렉터리 생성
  5. .env 및 docker-compose.yml 구성
  6. 필요한 바이너리를 이미지에 내장
  7. docker compose up -d
  8. 영속성 및 Gateway 접근 확인

  • VPS 프로비저닝

    Hetzner에서 Ubuntu 또는 Debian VPS를 생성한 다음 루트 사용자로 연결합니다.

    bash
    ssh root@YOUR_VPS_IP

    VPS를 폐기 가능한 인프라가 아니라 상태를 유지하는 인프라로 취급하세요.

  • Docker 설치(VPS에서)

    bash
    apt-get updateapt-get install -y git curl ca-certificatescurl -fsSL https://get.docker.com | sh

    확인합니다.

    bash
    docker --versiondocker compose version

  • OpenClaw 저장소 복제

    bash
    git clone https://github.com/openclaw/openclaw.gitcd openclaw

    이 가이드에서는 이미지에 내장한 모든 바이너리가 재시작 후에도 유지되도록 사용자 지정 이미지를 빌드합니다.

  • 영구 호스트 디렉터리 생성

    Docker 컨테이너는 일시적이므로 장기간 유지해야 하는 모든 상태는 호스트에 저장해야 합니다.

    bash
    mkdir -p /root/.openclaw/workspace # Set ownership to the container user (uid 1000):chown -R 1000:1000 /root/.openclaw

  • 환경 변수 구성

    저장소 루트에 .env를 생성합니다.

    bash
    OPENCLAW_IMAGE=openclaw:latestOPENCLAW_GATEWAY_TOKEN=OPENCLAW_GATEWAY_BIND=lanOPENCLAW_GATEWAY_PORT=18789 OPENCLAW_CONFIG_DIR=/root/.openclawOPENCLAW_WORKSPACE_DIR=/root/.openclaw/workspace GOG_KEYRING_PASSWORD=XDG_CONFIG_HOME=/home/node/.openclaw

    재시작 후에도 안정적인 Gateway 토큰을 .env에서 관리하려면 OPENCLAW_GATEWAY_TOKEN을 설정하세요. 그렇지 않으면 재시작 이후에도 클라이언트를 사용하기 전에 gateway.auth.token을 구성하세요. 둘 다 설정하지 않으면 OpenClaw는 해당 시작 과정에서만 유효한 런타임 전용 토큰을 사용합니다. GOG_KEYRING_PASSWORD에 사용할 키링 비밀번호를 생성합니다.

    bash
    openssl rand -hex 32

    이 파일을 커밋하지 마세요. 이 파일에는 OPENCLAW_GATEWAY_TOKEN과 같은 컨테이너/런타임 환경 변수가 포함됩니다. 저장된 공급자 OAuth/API 키 인증 정보는 마운트된 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json에 있습니다.

  • Docker Compose 구성

    docker-compose.yml을 생성하거나 업데이트합니다.

    yaml
    services:  openclaw-gateway:    image: ${OPENCLAW_IMAGE}    build: .    restart: unless-stopped    env_file:      - .env    environment:      - HOME=/home/node      - NODE_ENV=production      - TERM=xterm-256color      - OPENCLAW_GATEWAY_BIND=${OPENCLAW_GATEWAY_BIND}      - OPENCLAW_GATEWAY_PORT=${OPENCLAW_GATEWAY_PORT}      - OPENCLAW_GATEWAY_TOKEN=${OPENCLAW_GATEWAY_TOKEN}      - GOG_KEYRING_PASSWORD=${GOG_KEYRING_PASSWORD}      - XDG_CONFIG_HOME=${XDG_CONFIG_HOME}      - PATH=/home/linuxbrew/.linuxbrew/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin    volumes:      - ${OPENCLAW_CONFIG_DIR}:/home/node/.openclaw      - ${OPENCLAW_WORKSPACE_DIR}:/home/node/.openclaw/workspace    ports:      # Recommended: keep the Gateway loopback-only on the VPS; access via SSH tunnel.      # To expose it publicly, remove the `127.0.0.1:` prefix and firewall accordingly.      - "127.0.0.1:${OPENCLAW_GATEWAY_PORT}:18789"    command:      [        "node",        "dist/index.js",        "gateway",        "--bind",        "${OPENCLAW_GATEWAY_BIND}",        "--port",        "${OPENCLAW_GATEWAY_PORT}",        "--allow-unconfigured",      ]

    --allow-unconfigured는 초기 설정의 편의를 위한 옵션일 뿐, 실제 Gateway 구성을 대신하지 않습니다. 배포 환경에 맞게 인증(gateway.auth.token 또는 비밀번호)과 안전한 바인딩 모드를 반드시 설정하세요.

  • 공유 Docker VM 런타임 단계

    일반적인 Docker 호스트 절차는 공유 런타임 가이드를 따르세요.

  • Hetzner 전용 접근

    공유 빌드 및 실행 단계를 완료한 후 터널을 엽니다.

    사전 요구 사항: VPS의 sshd 구성이 TCP 포워딩을 허용하는지 확인하세요. SSH 구성을 강화한 경우 /etc/ssh/sshd_config를 확인하고 다음과 같이 설정합니다.

    text
    AllowTcpForwarding local

    local은 서버의 원격 포워딩은 차단하면서 노트북에서 ssh -L을 사용한 로컬 포워딩을 허용합니다. 이 값을 no로 설정하면 터널이 다음 오류와 함께 실패합니다. channel 3: open failed: administratively prohibited: open failed

    TCP 포워딩이 활성화되어 있는지 확인한 후 SSH 서비스를 다시 시작하고 (systemctl restart ssh) 노트북에서 다음 터널 명령을 실행합니다.

    bash
    ssh -N -L 18789:127.0.0.1:18789 root@YOUR_VPS_IP

    http://127.0.0.1:18789/을 열고 구성된 공유 비밀 값을 붙여 넣습니다. 이 가이드에서는 기본적으로 Gateway 토큰을 사용합니다. 비밀번호 인증으로 전환했다면 대신 구성된 비밀번호를 사용하세요.

    • 공유 영속성 매핑은 Docker VM 런타임에 있습니다.

    코드형 인프라(Terraform)

    코드형 인프라 워크플로를 선호하는 팀을 위해 커뮤니티에서 유지 관리하는 Terraform 설정은 다음 기능을 제공합니다.

    • 원격 상태 관리 기능을 갖춘 모듈식 Terraform 구성
    • cloud-init을 통한 자동 프로비저닝
    • 배포 스크립트(부트스트랩, 배포, 백업/복원)
    • 보안 강화(방화벽, UFW, SSH 전용 접근)
    • Gateway 접근을 위한 SSH 터널 구성

    저장소:

    이 접근 방식은 재현 가능한 배포, 버전 관리되는 인프라, 자동화된 재해 복구 기능을 추가하여 위의 Docker 설정을 보완합니다.

    다음 단계

    관련 문서

    Was this useful?
    On this page

    On this page