Ubuntu Server에 OpenClaw 설치해본 이야기 (Docker 환경)

요즘 AI 툴은 많지만, 대부분은 질문에 답해주는 수준에서 끝나는 경우가 많다.
그런데 OpenClaw는 조금 결이 달랐다. 공식 사이트에서부터 아예 "The AI that actually does things (실제로 일을 하는 AI)"라고 소개하고 있었고, 메일 정리나 캘린더 관리, 각종 채팅 앱 연동까지 지원하는 개인용 AI 어시스턴트라는 점이 흥미로웠다.

 

그래서 이번에는 내 노트북에 직접 OpenClaw를 설치해 봤다.
사실 처음에는 맥미니에 설치해서 돌려볼까 생각했다. 주변에서 맥미니를 작은 서버처럼 써서 이런 AI 에이전트를 돌리는 사람들이 꽤 있었기 때문이다.

나도 잠깐 맥미니 구매를 고민했지만, 집에 거의 쓰지 않고 굴러다니던 노트북이 하나 떠올랐다. 어차피 테스트 겸 설치해 보는 거라면 새 장비를 사기보다는 이 노트북에 먼저 설치해 보는 게 낫겠다 싶었다.

그래서 결국 이번 실험(?)은 집에 있던 노트북에 OpenClaw를 설치하는 것으로 시작하게 되었다.

설치 환경

CPU	Intel Core i7 10750H
GPU	Intel UHD Graphics + RTX 2060
RAM	32GB
OS	Ubuntu Server 24.04 LTS

 

설치 시작

OS 설치 먼저 노트북에 OS를 설치하는 것 부터 시작했다. 업무에서 사용하는 것 이외에, 라즈베리파이 같은 미니 PC가 아닌 개인용 노트북에 우분투를 설치하는 것은 처음이었다. Windows나 Ubuntu같은 GUI 환경을 설치하지 않고, CLI환경을 설치한 이유는 최대한 가벼운 환경으로 구동하고 싶었기 때문이다. 어차피 이 노트북은 모니터와 키보드를 항상 연결해서 사용하는 장비라기보다는, 집 한쪽에 두고 서버처럼 사용할 생각이었기 때문에 꼭 GUI가 필요하지는 않을 것 같았다. 필요한 패키지 (ssh, vim, git 등등) 을 설치 하는 것으로 OS설치를 마무리 했다.

 

작업을 위해 SSH 연결

위에서 쓴 것 처럼, 노트북은 덮어둔 상태로 집 한쪽에 두고 서버처럼 이용할 생각이었다.

그래서 실제 작업용 PC에서 SSH로 Ubuntu Server에 접속해 주었다.

Docker 설치

Ubuntu

공식 문서의 Install에 따라서 설치해 주었다.

# Add Docker's official GPG key:
sudo apt update
sudo apt install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Add the repository to Apt sources:
sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Signed-By: /etc/apt/keyrings/docker.asc
EOF

sudo apt update

 

위의 커맨드를 실행하기만 하면 설치가 완료된다.

 

OpenClaw 설치

Docker - OpenClaw

Docker 환경에서의 설치 방법에 대해서 공식 문서가 제공되어 있다.

 

이 문서에서 소개하는 Quick start의 순서로 아래의 명령어를 수행하라고 적혀있다.

./docker-setup.sh

 

나는 처음에 이 문서만 보고 리포지토리는 어디 있는데? 했더니, Install 문서에 적혀있었다 (...)

Install - OpenClaw

# 1. Clone and build
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build
pnpm build

 

그렇게 리포지토리를 클론 하고, 시작된 설치

 

위와 같은 화면이 나오기 시작하면서 이것저것 설정을 시작한다.

시행착오 1

설정을 완료했더니, 에러가 발생하기 시작했다.

◇ What now ───────────────────────────────────────────────────────────────╮ 
│ │ │ What now: https://openclaw.ai/showcase ("What People Are Building"). │ 
│ │ ├──────────────────────────────────────────────────────────────────────╯ 
│ └ Onboarding complete. Use the dashboard link above to control OpenClaw.
==> Docker gateway defaults
Container openclaw-openclaw-gateway-1 Starting
Container openclaw-openclaw-gateway-1 Started
Container openclaw-openclaw-cli-run-a067220028f5
Creating Container openclaw-openclaw-cli-run-a067220028f5
Created Error response from daemon: cannot join network namespace of container:
Container ddb6f3e2b2f44a8d1a835fedb9781b50dd616aaaf3da59cc07c71ece53edcdad is restarting, wait until the container is running

 

무언가의 문제로 컨테이너가 자동으로 재시작되고 있는 것 같았다.

# 로그 확인 명령어 수행
$ docker logs --tail=200 openclaw-openclaw-gateway-1

2026-03-05T14:15:28.620+00:00 Gateway failed to start:
Error: non-loopback Control UI requires gateway.controlUi.allowedOrigins (set explicit origins),
or set gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true to use Host-header origin fallback mode

2026-03-05T14:16:31.277+00:00 Gateway failed to start:
Error: non-loopback Control UI requires gateway.controlUi.allowedOrigins (set explicit origins),
or set gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true to use Host-header origin fallback mode

2026-03-05T14:17:33.967+00:00 Gateway failed to start:
Error: non-loopback Control UI requires gateway.controlUi.allowedOrigins (set explicit origins),
or set gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true to use Host-header origin fallback mode

 

로그 확인 결과, allowedOrigins설정이 되어있지 않아서 발생하는 문제 같았다.

dangerouslyAllowHostHeaderOriginFallback를 true로 해도 해결이 된다고 하지만, 설정값 이름에서부터 dangerous가 붙어있으니, Origin을 설정해 주기로 했다.

 

여기서 한 가지 문제가 발생했다.

그래서 그 설정은 어디서 하는데?

 

... 또다시 검색이 시작되었다.

 

찾아보니 다들 한마디로 /home/node/.openclaw/openclaw.json에 설정 파일이 있다고 한다.

그런데 지금 나는 OpenClaw 도커 컨테이너에서 기동 중이니, docker container에 접속해서 설정할 필요가 있다.

만약 이 글을 보고 해결을 하려고 한다면 깨우침 까지는 스킵하는 걸 추천한다. (시행착오 그 자체가 담겨있다)

 

그럼 컨테이너를 자동 재시작되게 하는 것을 방지하고, 어떻게든 수정을 해야 한다.

아래와 같은 명령어로, openclaw-cli config를 이용하는 상태라면 실행하기 전 설정하는 상태에서 멈출 것이라고 예상하고, 실행에 옮겼다.

$ sudo docker compose run --rm openclaw-cli config

예상대로 설정창이 나오기 시작했다.

이 상태에서, 터미널을 추가로 기동 하고, SSH로 연결을 해서, Docker Container의 정보를 확인해 보기로 했다.

다행히 문제없이 running 상태에서 유지되는 것 같았다.

그러면 이제 해당 컨테이너에 들어가서 수정하는 것만 남았다.

이걸로 파일이 확인되었다. 여기에 값을 수정하는 것만 남았다고 생각을 해서 기쁜 마음에 vi로 수정을 하려고 했다.

어림도 없었다. 이 컨테이너에는 vim이 설치되어있지 않은 것 같았다.

그래서 sed 명령어로 설정 값을 추가해 주었다.

  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "lan",
    "controlUi": {
      "allowedOrigins": [
        "http://192.xxx.xxx.xxx:18789",
        "http://localhost:18789",
        "http://127.0.0.1:18789"
      ]
    },

최종적으로는 이런 구조로 만들어 주었다.

지금 나의 환경은 외부에서 노트북에 있는 컨테이너로 접속을 할 예정이기 때문에, 노트북의 IP를 추가적으로 등록해 주었다.

그 후, 컨테이너를 재시작한 결과, 문제없이 running 상태가 유지되기 시작했다.

깨우침

openclaw리포지토리에는 .env파일이 존재한다.

OPENCLAW_CONFIG_DIR=/root/.openclaw
OPENCLAW_WORKSPACE_DIR=/root/.openclaw/workspace
OPENCLAW_GATEWAY_PORT=18789
OPENCLAW_BRIDGE_PORT=18790
OPENCLAW_GATEWAY_BIND=lan
OPENCLAW_GATEWAY_TOKEN=
OPENCLAW_IMAGE=openclaw:local
OPENCLAW_EXTRA_MOUNTS=
OPENCLAW_HOME_VOLUME=
OPENCLAW_DOCKER_APT_PACKAGES=
OPENCLAW_SANDBOX=
OPENCLAW_DOCKER_SOCKET=/var/run/docker.sock
DOCKER_GID=
OPENCLAW_INSTALL_DOCKER_CLI=
OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=

 

 

docker-compose파일에 있는 환경변수 OPENCLAW_CONFIG_DIR는 여기에서 선언되어 있었다.

즉 내 로컬의 /root/.openclaw 경로에 설정 값이 들어가 있다는 것이다.

# Ubuntu에서 실행
$ sudo cat /root/.openclaw/openclaw.json
{
  "meta": {
    "lastTouchedVersion": "2026.3.3",
    "lastTouchedAt": "2026-03-07T02:17:41.324Z"
  },
  "wizard": {
    "lastRunAt": "2026-03-07T02:17:41.293Z",
    "lastRunVersion": "2026.3.3",
    "lastRunCommand": "configure",
    "lastRunMode": "local"
  },

문제없이 해당 값을 읽어올 수 있었다.

 

시행착오 2

gateway에 접속했을 때 발생하는 문제

http://192.xxx.xxx.xxx:18789 로 접속했더니, 아래와 같은 에러가 발생했다.

control ui requires device identity (use HTTPS or localhost secure context)

# 서버상의 로그
openclaw-gateway-1 |
2026-03-06T15:20:37.067+00:00 [ws] closed before connect conn=9xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx7
remote=192.xxx.xxx.xxx fwd=n/a
origin=http://192.xxx.xxx.xxx:18789
host=192.xxx.xxx.xxx:18789
ua=Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)
AppleWebKit/537.36 (KHTML, like Gecko)
Chrome/145.0.0.0 Safari/537.36 code=1008
reason=control ui requires device identity (use HTTPS or localhost secure context)

 

Origin을 추가해도, 위와 같이 에러가 나온다.

조사해 보니, 깃허브에 버그 이슈가 있었다.

[Bug]: control ui requires device identity (use HTTPS or localhost secure context) · Issue #32473 · openclaw/openclaw

아직 대응은 되어있지 않은 것 같지만, 원인 자체는 LAN 주소의 평문 HTTP에서는 “device identity”를 만들 수 없어서, OpenClaw Control UI의 WebSocket 연결을 게이트웨이가 1008로 끊는 상황이었다.

 

그래서 가장 간단한 해결 방법으로 localhost로 접속을 하면 해결이 된다.

SSH 터널로 localhost로 접속하면 가능할 것이라 예상했고, 그 결과 문제없이 접속되었다.

ssh -L 18789:127.0.0.1:18789 username@192.xxx.xxx.xxx

다른 에러가 발생하지만, 이건 Gateway설정 시에 넣었던 토큰값을 넣어주면 해결될 문제다.

시행착오 3

첫 설정 때 문제없다고 생각했었지만, 실제로 기동 된 후 문제가 있음을 알게 되었다.

 

Agent 연동이 되어있지 않아서 생기는 문제였다.

 

처음 설정에서 OpenAI OAuth 연동 시, Fetch Failed라는 에러가 나오는 문제가 있었다.

 

이 문제에 대해서는 사진이 없지만, OAuth 연동을 하게 되면, Callback URL을 붙여 넣기 해달라고 한다.

아무런 작업 없이, 붙여 넣으면, Fetch Failed라는 에러가 나오면서 연동이 제대로 되지 않는다.

 

이 문제 또한 시행착오 2와 같은 방식으로 터널링을 해 주는 것으로 해결할 수 있다.

Callback URL에 들어가 있는 포트 번호를 개방해 주는 방식으로, 해결할 수 있다.

ssh -L 포트번호:127.0.0.1:포트번호 username@192.xxx.xxx.xxx

 

잡담

아직 초기설정을 마친 단계라서 아무런 스킬 / 권한이 등록되어있지 않은 상태라서 바보 그 자체를 보여준다.

 

기본적인 설정만 끝낸 상태라서 OpenClaw가 제대로 일을 하는 단계는 아니다.

앞으로 어떤 식으로 활용할 수 있을지 조금 더 실험해 볼 생각이다. (그런데 시행착오를 곁들인)