• HJ
    ActionMaskTech. Blog
Information
  • About
Blog
  • 전체
    17
  • AI
    4
  • Project
    5
  • Tip
    8
  • Tag
  • Github
  • RSS
  • ©2026 ActionMask. All Rights Reserved.
  1. Home

OpenClaw를 Docker에 설치하기

OpenClaw를 서버의 Docker 컨테이너에 설치하고 설정하는 방법을 안내하는 글입니다.
Tip
2026-02-17 01:14
19분

Information
클라우드 VPC 상 Ubuntu 24.04 LTS 환경에서 설치하는 가이드입니다. 기타 Linux 배포 환경 및 물리 서버 등에서도 유사하게 적용할 수 있습니다.

OpenClaw에 대해서 지난 글에서 간단히 소개한 바 있습니다. OpenClaw는 AI Agent 패키지로서, LLM 모델을 활용하여 다양한 작업을 자동화할 수 있도록 도와주는 도구입니다.
공식 홈페이지의 문서에서도 Docker 환경에 OpenClaw를 설치하는 방법에 대해 안내하고 있는데, 가상 혹은 물리 Linux 서버와 같이 GUI가 없는 환경에서 Docker 컨테이너 내에 OpenClaw를 격리시켜 설치하는 방법을 안내해 드리겠습니다.

참고로, OpenClaw를 Docker 내에 격리 시킨다고 보안 이슈가 완전히 해결되는 것은 아닙니다. 호스트의 자원에 함부로 접근할 수 없을 뿐이지, 에이전트가 클라우드 상의 개인 정보에 접근할 수 있도록 설정이 되어 있으면, 해당 정보를 조회하고 외부에 유출시킬 가능성이 있기 때문입니다. 따라서, OpenClaw가 접근할 수 있는 정보와 자원에 대해서는 신중하게 설정하는 것이 중요합니다.

OpenClaw Docker 설치하기

OpenClaw 공식 문서에서 Docker 환경 설치에 대한 문서가 존재 하지만, 맥이나 데스크톱 환경을 기준으로 작성된 것으로 보입니다. VPC 환경에 대한 설치 안내 가이드도 있긴 하지만 설치 후 설정 과정에 대해서 아예 언급이 없기 때문에, 리눅스 서버 환경에서 Docker 컨테이너에 OpenClaw를 설치하고 설정하는 방법을 이 글에서 안내해 드리고자 합니다. 다만, 본 가이드의 초기 설치 과정의 경우, OpenClaw 공식 문서를 참고하여 작성되었음을 미리 알려드립니다.

우선, 이전 글 Docker 설치 시 사용자를 docker 그룹에 추가하지 않는 이유를 참고하시면 좋을 것 같습니다. 저는 Docker를 항상 sudo 명령어와 함께 사용하기 때문에, Docker 그룹에 사용자를 추가하지 않고 있습니다. Docker 그룹에 사용자를 추가하면, 해당 사용자가 Docker 데몬에 대한 권한을 가지게 되어 보안 이슈가 발생할 수 있기 때문입니다.

OpenClaw 소스 코드 Clone 하기

Github의 OpenClaw Repository에서 소스 코드를 Clone 합니다.

git clone
openclaw
docker
llm
ai
agent
security
moltbook
ubuntu
In this article
  • OpenClaw Docker 설치하기
  • OpenClaw 소스 코드 Clone 하기
  • 각종 설정 파일을 위한 Volume 폴더 생성하기
  • 환경 변수 설정하기
  • docker-compose.yml 파일 수정하기
  • Dockerfile 수정하기
  • Docker 이미지 빌드 및 실행하기
  • OpenClaw Gateway 온보딩하기
  • WebUI 접속하기
  • Device 페어링 하기
  • 수동 파일 설정 (옵션)
  • Google 계정 연동하기
  • Chrome 브라우저 설치
  • 마치며
https://github.com/openclaw/openclaw.git
cd openclaw

각종 설정 파일을 위한 Volume 폴더 생성하기

OpenClaw는 node 사용자 (UID 1000)로 실행되도록 Docker 이미지가 설정되어 있습니다. OpenClaw의 설정 파일 등이 저장되는 폴더를 Volunme으로 마운트하기 위해 다음과 같이 설정할 수 있습니다.

mkdir ~/.openclaw
mkdir ~/.openclaw/workspace
 
cd ~/.openclaw
sudo chown -R 1000:1000 .openclaw

환경 변수 설정하기

다시 이전에 git clone한 폴더로 돌아와서 .env 파일을 생성합니다.

OPENCLAW_IMAGE=openclaw:latest
OPENCLAW_GATEWAY_TOKEN=<토큰 생성>
OPENCLAW_GATEWAY_BIND=lan
OPENCLAW_GATEWAY_PORT=18789
 
OPENCLAW_CONFIG_DIR=<생성한 .openclaw 폴더 경로>
OPENCLAW_WORKSPACE_DIR=<생성한 .openclaw/workspace 폴더 경로>
 
GOG_KEYRING_PASSWORD=<구글 계정 연동을 위한 키링 패스워드. 구글 계정 연동 안하면 생략 가능>
XDG_CONFIG_HOME=/home/node/.openclaw
Note
토큰 값은 openssl rand -hex 32 명령어로 생성할 수 있습니다.

docker-compose.yml 파일 수정하기

기본 데스크탑 환경을 위해 작성된 docker-compose.yml 파일을 VPC 환경에 맞게 수정합니다. GUI가 없는 서버 환경에서는 openclaw-gateway 서비스만 실행하면 됩니다. 다음과 같이 수정할 수 있습니다.

services:
  openclaw-gateway:
    image: ${OPENCLAW_IMAGE:-openclaw:local}
    build: .
    restart: unless-stopped
    env_file:
      - .env
    environment:
      - TZ=Asia/Seoul
      - HOME=/home/node
      - 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=/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:
      - "127.0.0.1:${OPENCLAW_GATEWAY_PORT}:18789"
    command:
      [
        "node",
        "dist/index.js",
        "gateway",
        "--bind",
        "${OPENCLAW_GATEWAY_BIND}",
        "--port",
        "${OPENCLAW_GATEWAY_PORT}",
        "--allow-unconfigured", # 초기 온보딩 없이 WebUI 접속을 위해 --allow-unconfigured 옵션 추가
      ]

Dockerfile 수정하기

필수 패키지 설치를 위해 Dockerfile을 다음과 같이 수정합니다. 공식 문서에서 GOG (구글 서비스 연동 유틸리티) 등을 미리 구워서 설치하라고 하지만, 추후에 Docker 컨테이너 내에서도 설치가 가능합니다. 따라서, Dockerfile에서는 필수 패키지 설치만 진행하도록 수정하겠습니다.

FROM node:22-bookworm
 
RUN curl -fsSL https://bun.sh/install | bash
ENV PATH="/root/.bun/bin:${PATH}"
 
RUN corepack enable
 
WORKDIR /app
 
# 필요한 패키지 미리 설치 (git curl jq ffmpeg build-essential)
RUN apt-get update && \
        DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends git curl jq ffmpeg build-essential && \
        apt-get clean && \
        rm -rf /var/lib/apt/lists/* /var/cache/apt/archives/*
 
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
COPY ui/package.json ./ui/package.json
COPY patches ./patches
COPY scripts ./scripts
 
RUN pnpm install --frozen-lockfile
 
COPY . .
RUN pnpm build
 
ENV OPENCLAW_PREFER_PNPM=1
RUN pnpm ui:install
RUN pnpm ui:build
 
ENV NODE_ENV=production
 
# 보안을 위해 기본 node 사용자로 파일 소유권 변경
RUN chown -R node:node /app
 
# OpenClaw 실행을 node 사용자로 설정
USER node
 
CMD ["node","dist/index.js"]

Docker 이미지 빌드 및 실행하기

이제 다음 명령어로 Docker 이미지를 빌드하고 OpenClaw Gateway를 실행할 수 있습니다.

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

OpenClaw Gateway 온보딩하기

OpenClaw Gateway가 실행되고 나면, 다음 명령어로 온보딩을 진행할 수 있습니다. 온보딩 과정에서는 OpenClaw Gateway에 접속하기 위한 토큰과 기타 설정을 입력하게 됩니다.

sudo docker compose exec openclaw-gateway node dist/index.js onboard

WebUI 접속하기

본 가이드는 원격 서버 환경에서 OpenClaw를 설치한 상태에기 때문에, WebUI에 접속하려면 SSH 터널링을 이용해서 로컬 머신에서 접속할 수 있도록 설정해야 합니다. 다음과 같이 SSH 터널링을 설정할 수 있습니다.

ssh -N -L 18789:127.0.0.1:18789 <사용자명>@<서버 IP 주소>
Information
만일 원격지 서버의 SSH 포트가 22번이 아니라면 ssh 명령어에 -p <SSH 포트 번호> 옵션을 추가해 주시면 됩니다.

브라우저를 띄워서 아래와 같이 주소를 입력해 줍니다.

http://127.0.0.1:18789?token=<초기에 .env 파일에 설정한 OPENCLAW_GATEWAY_TOKEN 값>

Device 페어링 하기

만일 WebUI에 접속했는데, paring 오류가 발생하면 다음 명령어로 Device 상태를 조회하고 페어링할 수 있습니다.

sudo docker compose exec openclaw-gateway node dist/index.js devices list

Pending 상태의 Device의 request id 값을 확인한 후, 다음 명령어로 해당 Device를 승인할 수 있습니다.

sudo docker compose exec openclaw-gateway node dist/index.js devices approve <request id>

수동 파일 설정 (옵션)

Note
이 부분은 OpenClaw의 모델 설정과 채널 연동을 수동으로 설정하는 방법에 대한 안내입니다. 만일 온보딩과 WebUI에서 설정하는 것을 마치셨다면, 이 부분은 건너뛰어도 됩니다.

모델 설정 및 채널 연동과 관련해서 이미 공식 문서에서도 상세하게 설명이 되어 있습니다. 차이는 저희는 도커 컨테이너 내에 OpenClaw를 설치하였다는 점 입니다.
OpenClaw의 경우 설정 파일을 /home/node/.openclaw/openclaw.json에 저장하게 되어 있습니다.
이미 저희는 위에서 설치 과정에서 호스트의 폴더로 Volume을 마운트하도록 설정했기 때문에, 호스트의 ~/.openclaw/openclaw.json 파일에 쉽게 접근하여 직접 수정할 수 있습니다.
기본적인 설정 파일은 다음과 같은 형태로 되어 있습니다.

{
  /*... 중략 ...*/
  "agents": {
    "defaults": {
      "model": {
        "primary": "<주 LLM 모델>"
      },
      "models": {
        "<LLM 모델>": {/*해당 모델의 설정 값들*/},
      },
      "workspace": "/home/node/.openclaw/workspace",
      "compaction": {
        "mode": "safeguard"
      },
      "maxConcurrent": 4,
      "subagents": {
        "maxConcurrent": 8
      }
    }
  },
  /*... 중략 ...*/
  "channels": {
    /* 텔레그램 사용 시 */
    "telegram": {
      "enabled": true,
      "dmPolicy": "pairing",
      "botToken": "<봇 토큰 값>",
      "groupPolicy": "allowlist",
      "streamMode": "partial"
    }
  },
  "gateway": {
    "mode": "local",
    "bind": "loopback",
    "auth": {
      "mode": "token",
      "token": "<설치 시 지정한 게이트웨이 토큰 값>",
      "allowTailscale": false
    }
  }, 
  
  /*... 중략 ...*/
}
Warning
설정 파일이 없다면 새로 생성하고, WebUI에서 Config 항목을 수정하면 설정 값이 적용됩니다.

Google 계정 연동하기

GOG 설치하기

Peter Steinberger가 개발한 GOG (Google OAuth Gateway)는 OpenClaw가 구글 계정과 연동할 수 있도록 도와주는 유틸리티입니다. GOG를 설치하려면 먼저 도커 컨테이너 내부로 접속합니다.

sudo docker exec -u root -it openclaw-openclaw-gateway-1 /bin/bash

먼저 GOG를 컴파일해서 설치하기 위해 GO 컴파일러를 설치합니다.

curl -fsSL https://go.dev/dl/go1.21.4.linux-amd64.tar.gz | tar -C /usr/local -xzvf -
export PATH=$PATH:/usr/local/go/bin

이제 GOG를 설치하기 위해 다음 명령어를 실행합니다.

git clone https://github.com/steipete/gogcli.git
cd gogcli
make
 
mv ./bin/gog /usr/local/bin/gog

만일 빌드가 실패하면, 미리 빌드된 파일을 다운로드받아 설치할 수 있습니다.

curl -L https://github.com/steipete/gogcli/releases/download/v0.11.0/gogcli_0.11.0_linux_amd64.tar.gz | tar -C /usr/local/bin -xzvf -

구글 API 설정하기

OpenClaw의 GOG는 기본적으로 구글의 API를 활용하여 구글 계정과 연동할 수 있도록 도와주는 유틸리티입니다. GOG를 사용하기 위해서는 먼저 구글 클라우드 플랫폼에서 OAuth 클라이언트 ID를 생성해야 합니다.

구글 클라우드 플랫폼에 접속 후 아래와 같이 설정을 진행합니다.

  • API 및 서비스 -> 사용자 인증 정보 -> + 사용자 인증 정보 만들기 -> OAuth 클라이언트 ID -> 동의화면 구성 -> 앱이름 및 이메일 입력 -> 대상: 외부 -> 연락처 정보 입력 및 만들기 클릭
  • OAuth 클라이언트 ID 만들기 화면 -> 애플리케이션 유형: 데스크톱 앱 -> 이름 입력 -> 만들기 -> Credentials JSON 파일 다운로드
  • Google 인증 플랫폼 -> 대상 -> 테스트 사용자 -> 본인의 현재 구글 계정 추가
  • 구글 클라우드 홈으로 이동 -> API 및 서비스 -> 라이브러리 -> Google Workspace -> 지메일, 캘린더, 드라이브, 시트, 닥스, 슬라이드 모두 사용으로 설정

GOG 설정

호스트에서 다운로드 받은 Credentials JSON 파일을 ~/.openclaw/credentials/google-credentials.json 경로에 저장합니다.

이제 도커 컨테이너로 진입하여 GOG를 설정합니다.

sudo docker exec -u root -it openclaw-openclaw-gateway-1 /bin/bash

GOG 유틸리티를 이용해서 JSON 파일을 지정합니다.

gog auth credentials ~/.openclaw/credentials/google-credentials.json

GUI가 없는 원격 환경에서 설치를 하기 때문에 다음과 같이 GOG를 두번에 걸쳐 인증을 수행합니다.

gog auth add you@gmail.com --services user --remote --step 1

연동을 위하는 서비스를 --services gmail,drive,calendar,sheets,docs 와 같이 Scope을 제한할 수 있고, --services user로 설정하면 모든 서비스에 대한 접근 권한을 요청할 수 있습니다. 다만, 보안상 필요한 서비스에 대해서만 권한을 부여하는 것을 권장드립니다.
위 명령어를 실행하면 인증을 위한 URL이 출력됩니다. 해당 URL을 복사해서 로컬 머신의 브라우저에 붙여넣기 합니다. 브라우저에서 구글 계정으로 로그인을 하고, 각 서비스의 액세스 항목을 설정할 수 있습니다. 편의상 모두 체크해도 무방합니다. 다음으로 진행이 되면 브라우저의 오류 페이지로 이동하게 됩니다.
이 때, 브라우저의 주소창에 있는 URL을 다시 복사해 둡니다.

gog auth add you@gmail.com --services user --remote --step 2 --auth-url 'http://127.0.0.1:<port>/oauth2/callback?code=...&state=...'

위와 같이 --auth-url 옵션에 복사해 둔 URL을 입력하면 최종적으로 인증이 완료됩니다. 이제 OpenClaw에서 구글 계정과 연동하여 지메일, 드라이브, 캘린더 등의 서비스를 활용할 수 있습니다.

Chrome 브라우저 설치

OpenClaw 에이전트가 웹을 겁색하는 방법 중 가장 강력한 수단은 직접 브라우저를 통해 웹사이트를 접속하는 것입니다. 로컬 PC에 설치한 것이 아닌 서버 환경에서 Docker 컨테이너 내부에 OpenClaw를 설치했기 때문에, 새로 Chrome 브라우저를 다운받아 설치해 주어야 합니다.
컨테이너 내부로 다시 아래 명령어로 접속합니다.

sudo docker exec -u root -it openclaw-openclaw-gateway-1 /bin/bash

Chrome 브라우저 설치를 위해 다음 명령어를 실행합니다.

wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
apt-get install -y ./google-chrome-stable_current_amd64.deb

openclaw.json 설정에 브라우저 관련 항목을 다음과 같이 수정해 줍니다.

{
  /*... 중략 ...*/
  "browser": {
      "enabled": true,
      "remoteCdpTimeoutMs": 1500,
      "remoteCdpHandshakeTimeoutMs": 3000,
      "executablePath": "/usr/bin/google-chrome",
      "headless": true,  /* GUI 없이 실행 */
      "noSandbox": true,
      "attachOnly": false,
      "defaultProfile": "openclaw", /* OpenClaw 전용 프로필 사용 */
      "profiles": {}
    },
  /*... 중략 ...*/
}

이제 호스트로 빠져나와서 OpenClaw Gateway를 재시작 해 줍니다.

sudo docker restart openclaw-openclaw-gateway-1

재시작 되면 에이전트가 웹 검색을 할 때, Chrome 브라우저를 활용해서 검색을 수행하게 됩니다. 에이전트가 스냅샷을 통해 웹페이지가 렌더링된 모습을 직접 볼 수 있기 때문에, 더 정확하고 빠르게 웹에서 정보를 수집할 수 있습니다.

마치며

서버 환경에서 Docker 컨테이너에 OpenClaw를 설치하는 방법에 대해서 간단하게 정리해 보았습니다. OpenClaw는 다양한 기능과 설정이 존재하기 때문에, 공식 문서 등을 살펴보면서 여러가지 설정을 조정하면서 사용해 보시는 것을 권장드립니다. 서버에 설치한 OpenClaw는 24시간 깨어있기 때문에 접근성이 매우 높고, Docker 컨테이너 내부에 설치할 경우 호스트의 모든 리소스에 접근하는 것을 방지하기 때문에 보안 문제의 일부분을 해소할 수 있는 방법입니다.
다만, 구글 서비스와 같이 개인 클라우드 서비스 상에 무제한 접근이 가능하기 때문에 항상 보안에 유의하면서 필요한 권한만 부여하고, 실제 액션을 취하기 전에 에이전트가 어떤 행동이나 스크립트를 실행할지 확인을 받도록 설정하는 것을 권장드립니다.
그럼, 즐거운 OpenClaw 라이프 되시길 바랍니다!

Tip 카테고리의 다른 글
Docker 사용자 그룹 권한 설정의 문제
Docker 사용자 그룹 권한 설정의 문제
Docker 사용 시 root 권한과 관련된 보안 이슈 및 권장 설정에 대한 글 입니다.
2026-02-10 23:12
Ubuntu 24.04 LTS에 r8125 랜카드 드라이버 설치
Ubuntu 24.04 LTS에 r8125 랜카드 드라이버 설치
Ubuntu 24.04 LTS에 r8125 랜카드 드라이버를 설치하는 방법을 알아봅니다.
2025-11-16 17:34
Vercel 배포 시 Serverless Function 250MB 제한 오류
Vercel 배포 시 Serverless Function 250MB 제한 오류
Next.js 배포 시 Serverless Function의 용량이 과도하게 잡히는 문제
2025-06-28 21:54
Next.js 프로젝트에서 MDX 코드 블럭 꾸미기
Next.js 프로젝트에서 MDX 코드 블럭 꾸미기
rehype-pretty-code 플러그인으로 MDX 코드 블럭을 꾸며보자.
2025-06-08 20:31
Python Flask를 위한 Gunicorn + NGINX 설정 방법
Python Flask를 위한 Gunicorn + NGINX 설정 방법
Ubuntu에서 Flask 어플리케이션을 Nginx와 Gunicorn을 이용해 서빙해보자.
2024-08-24 13:46
Ubuntu 설치 후 짜잘한 설정 팁
Ubuntu 설치 후 짜잘한 설정 팁
개인적으로 주로 하는 설정 작업을 정리해 보았습니다.
2023-03-02 11:36
Let's Encrypt 설치 및 자동 갱신 (feat. Cloudflare)
Let's Encrypt 설치 및 자동 갱신 (feat. Cloudflare)
무료 SSL 인증서를 설정하고 자동 갱신하자.
2022-02-16 17:34