OpenClaw

Your own personal AI assistant. Any OS. Any Platform. The lobster way. 🦞

Install

curl -fsSL https://openclaw.ai/install.sh | bash

온보딩 마법사 실행

openclaw onboard --install-daemon

Pi

Docker 로 시작하기

WARNING
혹시라도 패킷 필터 관련 문제가 있다면 iptables#Docker 트래픽 제어 항목 을 참조

docker를 설치한 후:

git clone https://github.com/openclaw/openclaw
./docker-setup.sh

이 스크립트가 하는 일:

게이트웨이 이미지 빌드
온보딩 마법사를 실행
선택적 공급자 설정
Docker Compose 를 통해 게이트웨이 시작.
게이트웨이 토큰을 생성하고 에 기록합니다. .env

선택적 환경 변수:

OPENCLAW_DOCKER_APT_PACKAGES - 빌드 중에 추가 apt 패키지 설치
OPENCLAW_EXTRA_MOUNTS - 추가 호스트 바인딩 마운트 추가
OPENCLAW_HOME_VOLUME - /home/node 이름의 볼륨 지속성.

그것이 끝난 후에:

브라우저에서 http://127.0.0.1:18789/ 접속.
토큰 컨트롤을 UI(설정 → 토큰)에 붙여넣습니다.
URL이 다시 필요하신가요? docker compose run --rm openclaw-cli dashboard --no-open

호스트에 config/workspace를 작성합니다:

~/.openclaw/ - 구성 디렉토리입니다. 여기에는 결국 OpenClaw 메모리, 구성, 타사 API 키 등이 포함됩니다.
~/.openclaw/workspace - 컨테이너 내부에서 실행될 때 에이전트가 직접 사용할 수 있는 파일이 가득 찬 작업 영역 디렉터리입니다. 에이전트가 만든 파일도 여기에 저장됩니다.

수동으로 작업을 진행하고 싶다면

docker build -t openclaw:local -f Dockerfile .
docker compose run --rm openclaw-cli onboard
docker compose up -d openclaw-gateway

만약 unauthorized 또는 disconnected (1008): pairing required 가 출력 된다면 대시 보드 링크 및 브라우저 장치를 승인해야 한다:

# 대시보드 링크 재생성
docker compose run --rm openclaw-cli dashboard --no-open

# 승인 대기 중인 디바이스 확인
docker compose run --rm openclaw-cli devices list

# 디바이스 승인 (출력된 requestId 사용)
docker compose run --rm openclaw-cli devices approve <requestId>

접속 방법

그냥 접속하면 대시보드에서 다음과 같이 출력된다:

disconnected (1008): control ui requires HTTPS or localhost (secure context)

보안의 문제로 인해 localhost 도메인 또는 https:// 스키마로 접속 가능하다.

따라서 로컬 PC 터미널에서 SSH 터널링으로 접속해야 한다:

ssh -N -L 18789:127.0.0.1:18789 user@<원격PC_IP>

이후 http://localhost:18789 으로 접속하면 된다.

텔레그램 등록

해당 챗봇이 있는 채팅방에 아무거나 입력하면 다음과 같이 출력된다:

OpenClaw: access not configured.

Your Telegram user id: NNNNNNNN

Pairing code: XXXXXXXX

Ask the bot owner to approve with:
openclaw pairing approve telegram <code>

나와있는 코드를 사용하여 명령을 실행하자.

openclaw pairing approve telegram XXXXXXXX

만약 Docker 컨테이너에서 직접 실행한다면 다음 명령으로 실행하자:

docker compose exec openclaw-gateway node dist/index.js pairing approve telegram XXXXXXXX

wakeMode

OpenClaw cron job의 실행 방식을 결정하는 설정. 명시하지 않으면 next-heartbeat가 기본값.

값

값	설명	사용 사례
`now`	스케줄 시간에 즉시 실행	정시 알림, 정확한 타이밍 필요 시
`next-heartbeat`	스케줄 시간 이후 다음 heartbeat에서 실행	배터리/리소스 절약, 느슨한 타이밍 허용 시

동작 방식

now

스케줄된 시간(예: 08:00)에 게이트웨이가 직접 job 실행
게이트웨이 프로세스가 타이머를 관리
정확한 실행 시간 보장

next-heartbeat

스케줄 시간이 지나도 바로 실행하지 않음
다음 heartbeat poll이 올 때까지 대기
heartbeat 주기에 따라 지연 발생 가능
heartbeat가 비활성화되어 있으면 영원히 실행 안 됨

주의사항

next-heartbeat는 heartbeat polling이 활성화되어 있어야 함
heartbeat 간격이 길면 알림 지연 발생
정시 알림이 필요하면 반드시 now 사용

예시

{
  "name": "아침 알림",
  "schedule": { "kind": "cron", "expr": "0 22 * * *", "tz": "UTC" },
  "wakeMode": "now",
  "sessionTarget": "isolated",
  "payload": {
    "kind": "agentTurn",
    "message": "알림 내용"
  }
}

Troubleshooting

gateway closed (1006 abnormal closure (no close frame)): no close reason

디바이스 등록을 다음과 같이 진행했을 때:

docker compose run --rm openclaw-cli devices list

를 치면 다음 에러가 출력됨:

WARN[0000] The "CLAUDE_WEB_COOKIE" variable is not set. Defaulting to a blank string.
WARN[0000] The "CLAUDE_AI_SESSION_KEY" variable is not set. Defaulting to a blank string.
WARN[0000] The "CLAUDE_WEB_SESSION_KEY" variable is not set. Defaulting to a blank string.
WARN[0000] The "CLAUDE_WEB_COOKIE" variable is not set. Defaulting to a blank string.
WARN[0000] The "CLAUDE_AI_SESSION_KEY" variable is not set. Defaulting to a blank string.
WARN[0000] The "CLAUDE_WEB_SESSION_KEY" variable is not set. Defaulting to a blank string.
Container openclaw-openclaw-cli-run-4767ca06b094 Creating
Container openclaw-openclaw-cli-run-4767ca06b094 Created

🦞 OpenClaw 2026.2.3 (unknown) — I read logs so you can keep pretending you don't have to.

│
◇
[openclaw] CLI failed: Error: gateway closed (1006 abnormal closure (no close frame)): no close reason
Gateway target: ws://127.0.0.1:18789
Source: local loopback
Config: /home/node/.openclaw/openclaw.json
Bind: lan
    at Object.onClose (file:///app/dist/call-BxBOsbXG.js:262:10)
    at WebSocket.<anonymous> (file:///app/dist/client-i9GLCujO.js:1400:23)
    at WebSocket.emit (node:events:519:28)
    at WebSocket.emitClose (/app/node_modules/.pnpm/[email protected]/node_modules/ws/lib/websocket.js:263:12)
    at emitErrorAndClose (/app/node_modules/.pnpm/[email protected]/node_modules/ws/lib/websocket.js:1047:13)
    at ClientRequest.<anonymous> (/app/node_modules/.pnpm/[email protected]/node_modules/ws/lib/websocket.js:886:5)
    at ClientRequest.emit (node:events:519:28)
    at emitErrorEvent (node:_http_client:107:11)
    at Socket.socketErrorListener (node:_http_client:574:5)
    at Socket.emit (node:events:519:28)

이 경우 gateway 컨테이너에서 직접 실행하세요:

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

unauthorized: gateway token mismatch (set gateway.remote.token to match gateway.auth.token)

디바이스 등록시:

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

다음과 같이 출력된다면:

🦞 OpenClaw 2026.2.3 (unknown) — I'm not magic—I'm just extremely persistent with retries and coping strategies.

│
gateway connect failed: Error: unauthorized: gateway token mismatch (set gateway.remote.token to match gateway.auth.token)
◇
[openclaw] CLI failed: Error: gateway closed (1008): unauthorized: gateway token mismatch (set gateway.remote.token to match gateway.auth.token)
Gateway target: ws://127.0.0.1:18789
Source: local loopback
Config: /home/node/.openclaw/openclaw.json
Bind: lan
    at Object.onClose (file:///app/dist/call-BxBOsbXG.js:262:10)
    at WebSocket.<anonymous> (file:///app/dist/client-i9GLCujO.js:1400:23)
    at WebSocket.emit (node:events:519:28)
    at WebSocket.emitClose (/app/node_modules/.pnpm/[email protected]/node_modules/ws/lib/websocket.js:273:10)
    at Socket.socketOnClose (/app/node_modules/.pnpm/[email protected]/node_modules/ws/lib/websocket.js:1346:15)
    at Socket.emit (node:events:519:28)
    at TCP.<anonymous> (node:net:346:12)

token mismatch라고 나옵니다. 연결은 되지만 인증에서 실패하는 겁니다. 설정 파일의 토큰을 확인해보세요:

# 1. 컨테이너 내부 설정
docker compose exec openclaw-gateway cat /home/node/.openclaw/openclaw.json | grep -A2 token

# 2. 호스트 설정
cat ~/.openclaw/openclaw.json | grep -A2 token

# 3. .env 파일
cat .env | grep TOKEN

위의 세 토큰이 모두 동일해야 한다.

만약 토큰이 lNXrjBP5su9SUP4spBfNTaEYZy67WmB7b25ex4yYeXAENSDW 일 경우 다음과 같이 토큰을 직접 지정할 수 있다:

docker compose exec openclaw-gateway node dist/index.js devices list --token "lNXrjBP5su9SUP4spBfNTaEYZy67WmB7b25ex4yYeXAENSDW"

출력된 Pending 테이블의 Request 컬럼에 UUID 를 사용하여 등록하면 된다. Request UUID 가 99a9713e-be0d-469f-bca4-25153a12a670 일 경우:

docker compose exec openclaw-gateway node dist/index.js devices approve 99a9713e-be0d-469f-bca4-25153a12a670 --token "lNXrjBP5su9SUP4spBfNTaEYZy67WmB7b25ex4yYeXAENSDW"