Synology NAS에 OpenClaw 설치하기

들어가며

이번 글에서는 Synology NAS에 OpenClaw를 Docker Compose 기반으로 신규 설치하는 과정을 정리한다.

Synology DSM 환경은 일반적인 Ubuntu 서버와 다르다. NAS에 직접 Node.js/npm 기반으로 OpenClaw를 설치할 수도 있지만, 장기 운영 관점에서는 Docker Compose 기반 구성이 더 깔끔하다.

Docker Compose로 구성하면 다음 장점이 있다.

OpenClaw 실행 환경을 Synology host와 분리할 수 있음
gateway와 CLI 실행 환경을 일관되게 유지할 수 있음
재부팅 후 자동 실행을 restart: unless-stopped로 처리할 수 있음
.openclaw 설정과 workspace를 volume으로 분리해 보존할 수 있음
GitHub CLI, ripgrep, jq 같은 코딩 작업용 도구를 이미지에 함께 포함할 수 있음
Synology 터미널의 TTY/리치 출력 문제를 우회하기 쉬움

최종 구성

최종 디렉터리 구조는 다음과 같이 잡는다.

/volume1/docker/openclaw
├── docker-compose.yml
├── Dockerfile
├── .env
└── .openclaw/
    ├── workspace/
    ├── logs/
    └── cron/

컨테이너 내부에서는 OpenClaw 설정 경로를 다음처럼 사용한다.

/home/node/.openclaw
/home/node/.openclaw/workspace

즉, NAS host의 실제 경로는 다음이지만,

/volume1/docker/openclaw/.openclaw

컨테이너 내부에서는 다음 경로로 보이게 한다.

/home/node/.openclaw

이 구조의 핵심은 다음과 같다.

OpenClaw 설정과 workspace는 NAS의 /volume1/docker/openclaw/.openclaw에 보존
컨테이너는 언제든 삭제/재생성 가능
OpenClaw CLI는 host에 직접 설치하지 않고 openclaw-cli 컨테이너로 실행
OpenClaw gateway는 openclaw-gateway 컨테이너로 상시 실행

사전 준비

Synology NAS에는 DSM의 Container Manager가 설치되어 있어야 한다.

SSH 터미널에서 Docker와 Compose가 정상 동작하는지 확인한다.

sudo docker version
sudo docker compose version

Synology에서는 일반 사용자 계정이 Docker daemon socket에 직접 접근하지 못하는 경우가 많다.

확인:

ls -al /var/run/docker.sock

예시:

srw-rw---- 1 root root 0 docker.sock

이 경우 일반 사용자로는 docker pull 같은 명령이 실패한다.

따라서 이 글에서는 모든 Docker 명령을 다음처럼 sudo 기준으로 실행한다.

sudo docker compose ...

설치 디렉터리 생성

OpenClaw Compose 프로젝트용 디렉터리를 만든다.

sudo mkdir -p /volume1/docker/openclaw
cd /volume1/docker/openclaw

OpenClaw 설정과 workspace를 저장할 .openclaw 디렉터리도 미리 만든다.

sudo mkdir -p /volume1/docker/openclaw/.openclaw
sudo mkdir -p /volume1/docker/openclaw/.openclaw/workspace
sudo mkdir -p /volume1/docker/openclaw/.openclaw/logs
sudo mkdir -p /volume1/docker/openclaw/.openclaw/cron

권한 정리

OpenClaw Docker 이미지는 컨테이너 내부에서 node 사용자로 실행된다. 일반적으로 이 사용자의 UID는 1000이다.

따라서 host의 .openclaw 디렉터리를 컨테이너 내부 사용자가 쓸 수 있도록 권한을 맞춘다.

sudo chown -R 1000:1000 /volume1/docker/openclaw/.openclaw

권한이 맞지 않으면 다음과 같은 에러가 발생할 수 있다.

EACCES: permission denied, open '/home/node/.openclaw/logs/config-health.json'

커스텀 Dockerfile 작성

OpenClaw 기본 이미지만으로도 gateway 실행은 가능하다. 하지만 코딩 에이전트 용도로도 사용할 계획이라면 gh, ripgrep, jq를 함께 넣어두는 것이 편하다.

/volume1/docker/openclaw/Dockerfile

FROM ghcr.io/openclaw/openclaw:latest

USER root

RUN apt-get update \
  && apt-get install -y --no-install-recommends gh ripgrep jq \
  && rm -rf /var/lib/apt/lists/*

USER node

각 도구의 용도는 다음과 같다.

gh: GitHub CLI
ripgrep: 빠른 코드 검색용 rg
jq: JSON 출력 확인 및 가공

`.env` 작성

/volume1/docker/openclaw/.env

OPENCLAW_CONFIG_DIR=/volume1/docker/openclaw/.openclaw
OPENCLAW_WORKSPACE_DIR=/volume1/docker/openclaw/.openclaw/workspace

OPENCLAW_GATEWAY_PORT=18789
OPENCLAW_TZ=Asia/Seoul

# GitHub CLI 또는 GitHub Copilot 연동이 필요할 경우 입력
GH_TOKEN=
GITHUB_TOKEN=
COPILOT_GITHUB_TOKEN=

.env에는 GitHub token, Copilot token 같은 민감정보가 들어갈 수 있으므로 권한을 제한한다.

sudo chmod 600 /volume1/docker/openclaw/.env

docker-compose.yml 작성

/volume1/docker/openclaw/docker-compose.yml

services:
  openclaw-gateway:
    build:
      context: .
      dockerfile: Dockerfile
    image: local/openclaw-gh:latest
    container_name: openclaw-gateway
    env_file:
      - .env
    environment:
      HOME: /home/node
      OPENCLAW_HOME: /home/node
      TERM: xterm-256color

      OPENCLAW_STATE_DIR: /home/node/.openclaw
      OPENCLAW_CONFIG_PATH: /home/node/.openclaw/openclaw.json
      OPENCLAW_CONFIG_DIR: /home/node/.openclaw
      OPENCLAW_WORKSPACE_DIR: /home/node/.openclaw/workspace

      OPENCLAW_GATEWAY_TOKEN: ${OPENCLAW_GATEWAY_TOKEN:-}
      OPENCLAW_ALLOW_INSECURE_PRIVATE_WS: ${OPENCLAW_ALLOW_INSECURE_PRIVATE_WS:-}
      OPENCLAW_DISABLE_BONJOUR: ${OPENCLAW_DISABLE_BONJOUR:-}

      GH_TOKEN: ${GH_TOKEN:-}
      GITHUB_TOKEN: ${GITHUB_TOKEN:-}
      COPILOT_GITHUB_TOKEN: ${COPILOT_GITHUB_TOKEN:-}

      TZ: ${OPENCLAW_TZ:-Asia/Seoul}
    volumes:
      - ${OPENCLAW_CONFIG_DIR}:/home/node/.openclaw
      - ${OPENCLAW_WORKSPACE_DIR}:/home/node/.openclaw/workspace
    ports:
      - "127.0.0.1:${OPENCLAW_GATEWAY_PORT:-18789}:18789"
    extra_hosts:
      - "host.docker.internal:host-gateway"
    cap_drop:
      - NET_RAW
      - NET_ADMIN
    security_opt:
      - no-new-privileges:true
    init: true
    restart: unless-stopped
    command:
      [
        "node",
        "dist/index.js",
        "gateway",
        "--bind",
        "lan",
        "--port",
        "18789"
      ]
    healthcheck:
      test:
        [
          "CMD",
          "node",
          "-e",
          "fetch('http://127.0.0.1:18789/healthz').then((r)=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"
        ]
      interval: 30s
      timeout: 5s
      retries: 5
      start_period: 20s

  openclaw-cli:
    image: local/openclaw-gh:latest
    network_mode: "service:openclaw-gateway"
    env_file:
      - .env
    environment:
      HOME: /home/node
      OPENCLAW_HOME: /home/node
      TERM: xterm-256color

      OPENCLAW_STATE_DIR: /home/node/.openclaw
      OPENCLAW_CONFIG_PATH: /home/node/.openclaw/openclaw.json
      OPENCLAW_CONFIG_DIR: /home/node/.openclaw
      OPENCLAW_WORKSPACE_DIR: /home/node/.openclaw/workspace

      OPENCLAW_GATEWAY_TOKEN: ${OPENCLAW_GATEWAY_TOKEN:-}
      OPENCLAW_ALLOW_INSECURE_PRIVATE_WS: ${OPENCLAW_ALLOW_INSECURE_PRIVATE_WS:-}

      GH_TOKEN: ${GH_TOKEN:-}
      GITHUB_TOKEN: ${GITHUB_TOKEN:-}
      COPILOT_GITHUB_TOKEN: ${COPILOT_GITHUB_TOKEN:-}

      BROWSER: echo
      TZ: ${OPENCLAW_TZ:-Asia/Seoul}
    volumes:
      - ${OPENCLAW_CONFIG_DIR}:/home/node/.openclaw
      - ${OPENCLAW_WORKSPACE_DIR}:/home/node/.openclaw/workspace
    cap_drop:
      - NET_RAW
      - NET_ADMIN
    security_opt:
      - no-new-privileges:true
    stdin_open: true
    tty: true
    init: true
    entrypoint: ["node", "dist/index.js"]
    depends_on:
      - openclaw-gateway

여기서 중요한 점은 두 가지다.

첫째, .env의 OPENCLAW_CONFIG_DIR와 OPENCLAW_WORKSPACE_DIR는 NAS host 경로다.

OPENCLAW_CONFIG_DIR=/volume1/docker/openclaw/.openclaw
OPENCLAW_WORKSPACE_DIR=/volume1/docker/openclaw/.openclaw/workspace

둘째, compose의 environment 안에 있는 OPENCLAW_CONFIG_DIR와 OPENCLAW_WORKSPACE_DIR는 컨테이너 내부 경로다.

OPENCLAW_CONFIG_DIR: /home/node/.openclaw
OPENCLAW_WORKSPACE_DIR: /home/node/.openclaw/workspace

둘을 혼동하면 컨테이너 안에서 host 경로를 만들려고 하거나, permission error가 발생할 수 있다.

bridge 모드로 운영하는 이유

이 compose 파일은 Docker bridge 모드를 기준으로 한다.

ports:
  - "127.0.0.1:18789:18789"

이 설정은 OpenClaw gateway를 NAS의 127.0.0.1:18789에만 노출한다.

즉, 같은 내부망에 있는 다른 기기에서 직접 http://NAS_IP:18789로 접근할 수 없고, SSH 터널을 통해서만 접근한다.

이 방식의 장점은 다음과 같다.

gateway를 외부 네트워크에 직접 노출하지 않음
기존 SSH 터널 접속 방식과 잘 맞음
Synology 방화벽과 별개로 노출 범위를 줄일 수 있음

왜 gateway bind는 `lan`인가

처음에는 gateway를 loopback으로 두는 것이 더 안전해 보인다.

하지만 Docker bridge 모드에서는 컨테이너 내부의 loopback은 NAS host의 loopback이 아니라 컨테이너 자기 자신의 loopback이다.

따라서 host의 published port를 통해 컨테이너 gateway에 접근하려면, 컨테이너 내부 OpenClaw는 loopback이 아니라 lan으로 bind하는 것이 안전하다.

compose에서는 다음처럼 설정했다.

command:
  [
    "node",
    "dist/index.js",
    "gateway",
    "--bind",
    "lan",
    "--port",
    "18789"
  ]

host 쪽 포트는 여전히 127.0.0.1:18789에만 열어두기 때문에 외부 노출 범위는 제한된다.

커스텀 이미지 빌드

Compose 프로젝트 폴더로 이동한다.

cd /volume1/docker/openclaw

커스텀 이미지를 빌드한다.

sudo docker compose build

캐시 없이 다시 빌드하려면 다음 명령을 사용한다.

sudo docker compose build --no-cache

OpenClaw gateway 실행

gateway를 실행한다.

sudo docker compose up -d openclaw-gateway

빌드와 실행을 한 번에 하려면 다음 명령을 사용한다.

sudo docker compose up -d --build openclaw-gateway

상태 확인:

sudo docker compose ps

로그 확인:

sudo docker compose logs -f openclaw-gateway

health check

NAS host에서 gateway health check를 확인한다.

curl -fsS http://127.0.0.1:18789/healthz
curl -fsS http://127.0.0.1:18789/readyz

정상이라면 HTTP 응답이 반환된다.

SSH 터널로 대시보드 접속

이 구성에서는 gateway가 NAS의 127.0.0.1:18789에만 노출되어 있으므로, 외부 기기에서는 SSH 터널을 통해 접속한다.

ssh -L 18789:127.0.0.1:18789 agent@<NAS_IP>

그 다음 브라우저에서 접속한다.

http://127.0.0.1:18789

이 방식은 브라우저의 localhost secure context 조건을 만족시키기 쉽고, OpenClaw gateway를 내부망에 직접 노출하지 않아도 된다.

OpenClaw CLI 실행 방식

Docker Compose 구조에서는 host에 openclaw CLI를 직접 설치하지 않는다. 대신 openclaw-cli 서비스를 통해 실행한다.

버전 확인:

sudo docker compose run -T --rm openclaw-cli --version

상태 확인:

sudo docker compose run -T --rm openclaw-cli status --json

doctor:

sudo docker compose run -T --rm openclaw-cli doctor

모델 상태 확인:

sudo docker compose run -T --rm openclaw-cli models status --json

cron 목록 확인:

sudo docker compose run -T --rm openclaw-cli cron list

`-T` 옵션을 언제 쓰고 언제 빼야 하나

Docker Compose에서 -T는 pseudo-TTY 할당을 끄는 옵션이다.

Synology 터미널에서 리치 출력이 불안정하거나, JSON 출력만 확인할 때는 -T를 붙이는 편이 안정적이다.

예:

sudo docker compose run -T --rm openclaw-cli status --json
sudo docker compose run -T --rm openclaw-cli doctor

하지만 로그인, wizard, device auth처럼 interactive TTY가 필요한 명령에는 -T를 붙이면 안 된다.

잘못된 예:

sudo docker compose run -T --rm openclaw-cli models auth login --provider github-copilot

이 경우 다음 에러가 날 수 있다.

models auth login requires an interactive TTY

올바른 예:

sudo docker compose run --rm openclaw-cli models auth login-github-copilot

정리하면 다음과 같다.

상태 확인, doctor, JSON 출력 → -T 사용
로그인, wizard, device auth → -T 제거

컨테이너 내부 shell 접속

CLI 컨테이너 shell:

sudo docker compose run --rm --entrypoint sh openclaw-cli

실행 중인 gateway 컨테이너 shell:

sudo docker compose exec openclaw-gateway sh

명령만 실행:

sudo docker compose run -T --rm --entrypoint sh openclaw-cli -lc 'pwd && ls -al'

설치한 도구 확인:

sudo docker compose run -T --rm --entrypoint sh openclaw-cli -lc 'gh --version && rg --version && jq --version'

GitHub CLI 토큰 설정

컨테이너 안에서 gh를 사용하려면 GitHub token을 .env에 넣는다.

GH_TOKEN=github_pat_xxxxxxxxxxxxxxxxx
GITHUB_TOKEN=github_pat_xxxxxxxxxxxxxxxxx

.env 수정 후 gateway를 재시작한다.

sudo docker compose restart openclaw-gateway

컨테이너 안에서 gh 인증 상태 확인:

sudo docker compose run -T --rm --entrypoint gh openclaw-cli auth status

repo 접근 확인:

sudo docker compose run -T --rm --entrypoint gh openclaw-cli repo list

.env에는 민감정보가 들어가므로 공개 저장소에 올리면 안 된다.

자주 쓰는 명령어

프로젝트 폴더 이동

cd /volume1/docker/openclaw

이미지 빌드

sudo docker compose build

캐시 없이 빌드

sudo docker compose build --no-cache

gateway 실행

sudo docker compose up -d openclaw-gateway

빌드 포함 실행

sudo docker compose up -d --build openclaw-gateway

gateway 로그 확인

sudo docker compose logs -f openclaw-gateway

gateway 재시작

sudo docker compose restart openclaw-gateway

중지 및 컨테이너 제거

sudo docker compose down

상태 JSON 확인

sudo docker compose run -T --rm openclaw-cli status --json

doctor 실행

sudo docker compose run -T --rm openclaw-cli doctor

shell 접속

sudo docker compose run --rm --entrypoint sh openclaw-cli

설치 도구 확인

sudo docker compose run -T --rm --entrypoint sh openclaw-cli -lc 'gh --version && rg --version && jq --version'

업데이트

sudo docker compose pull
sudo docker compose build --no-cache
sudo docker compose down
sudo docker compose up -d openclaw-gateway

자주 만난 에러와 해결

1. `no configuration file provided: not found`

no configuration file provided: not found

원인:

docker-compose.yml이 없는 디렉터리에서 docker compose 실행

해결:

cd /volume1/docker/openclaw
sudo docker compose run -T --rm openclaw-cli doctor

또는 compose 파일 경로를 직접 지정한다.

sudo docker compose \
  -f /volume1/docker/openclaw/docker-compose.yml \
  --env-file /volume1/docker/openclaw/.env \
  run -T --rm openclaw-cli doctor

2. `.openclaw` EACCES

EACCES: permission denied, open '/home/node/.openclaw/logs/config-health.json'

원인:

컨테이너 내부 node 사용자(uid 1000)가 host bind mount 폴더에 쓰기 불가

해결:

sudo chown -R 1000:1000 /volume1/docker/openclaw/.openclaw

3. Docker socket permission denied

permission denied while trying to connect to the Docker daemon socket

원인:

agent 계정이 /var/run/docker.sock 접근 권한 없음

해결:

sudo docker compose ...

Synology에서는 Docker socket 권한을 넓히는 것보다 sudo 또는 DSM Container Manager UI를 쓰는 편이 안전하다.

4. `models auth login requires an interactive TTY`

models auth login requires an interactive TTY

원인:

interactive login 명령에 -T 옵션을 붙임

해결:

sudo docker compose run --rm openclaw-cli models auth login-github-copilot

상태 확인이나 JSON 출력에는 -T를 쓰고, 로그인류 명령에는 -T를 빼면 된다.

DSM Container Manager에서 관리하기

SSH에서 Compose를 실행해도 되지만, DSM UI에서는 Container Manager의 Project로 관리할 수 있다.

흐름:

/volume1/docker/openclaw 폴더 생성
Dockerfile, .env, docker-compose.yml 작성
DSM Container Manager → Project → Create
경로를 /volume1/docker/openclaw로 지정
compose 내용을 확인하고 생성

이렇게 하면 DSM UI에서도 컨테이너 상태, 로그, 재시작을 확인할 수 있다.

마무리

Synology NAS에 OpenClaw를 Docker Compose로 신규 설치하면 host 환경에 직접 의존하지 않고 안정적으로 gateway와 CLI를 운영할 수 있다.

이번 구성에서 가장 중요한 포인트는 다음 네 가지다.

.openclaw는 host에 보존하고 컨테이너에는 /home/node/.openclaw로 mount한다.
OpenClaw 컨테이너는 uid 1000의 node 사용자로 실행되므로 host 폴더 권한을 맞춘다.
bridge 모드에서는 gateway bind를 lan으로 두고, host에는 127.0.0.1:18789만 노출한다.
CLI 명령은 openclaw-cli 컨테이너로 실행하고, 비대화형 명령에는 -T를 붙인다.

이 구조를 잡아두면 OpenClaw gateway 실행, CLI 상태 확인, Telegram 채널 설정, 모델 인증, cron 테스트까지 모두 Docker Compose 안에서 일관되게 관리할 수 있다.