Hetzner

VPS 프로비저닝

Hetzner에서 Ubuntu 또는 Debian VPS를 생성합니다.

root로 연결합니다:

ssh root@YOUR_VPS_IP

이 가이드는 VPS가 상태를 유지한다고 가정합니다. 이를 폐기 가능한 인프라로 취급하지 마세요.

Docker 설치(VPS에서)

apt-get update
apt-get install -y git curl ca-certificates
curl -fsSL https://get.docker.com | sh

확인:

docker --version
docker compose version

OpenClaw 저장소 클론

git clone https://github.com/openclaw/openclaw.git
cd openclaw

이 가이드는 바이너리 지속성을 보장하기 위해 사용자 지정 이미지를 빌드한다고 가정합니다.

영구 호스트 디렉터리 생성

Docker 컨테이너는 일시적입니다. 장기 보존 상태는 모두 호스트에 있어야 합니다.

mkdir -p /root/.openclaw/workspace

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

환경 변수 구성

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

OPENCLAW_IMAGE=openclaw:latest
OPENCLAW_GATEWAY_TOKEN=
OPENCLAW_GATEWAY_BIND=lan
OPENCLAW_GATEWAY_PORT=18789

OPENCLAW_CONFIG_DIR=/root/.openclaw
OPENCLAW_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에 붙여넣으세요:

openssl rand -hex 32

이 파일을 커밋하지 마세요.

이 .env 파일은 OPENCLAW_GATEWAY_TOKEN 같은 컨테이너/런타임 env용입니다. 저장된 제공자 OAuth/API 키 인증은 마운트된 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json에 있습니다.

Docker Compose 구성

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

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를 확인하고 다음을 설정하세요:

AllowTcpForwarding local

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

TCP 포워딩이 활성화되었는지 확인한 뒤 SSH 서비스를 재시작하고 (systemctl restart ssh) 노트북에서 터널을 실행하세요:

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

엽니다:

http://127.0.0.1:18789/

구성한 공유 비밀값을 붙여넣으세요. 이 가이드는 기본적으로 gateway 토큰을 사용합니다. 비밀번호 인증으로 전환했다면 대신 해당 비밀번호를 사용하세요.