OpenClaw

lastmod 2026-05-27created 2026-01-3125 edits

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

Install

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

Run the onboarding wizard

openclaw onboard --install-daemon

Pi

Getting started with Docker

WARNING
If you run into any packet filter issues, see iptables#Docker traffic control

After installing docker:

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

What this script does:

Builds the gateway image
Runs the onboarding wizard
Optional provider setup
Starts the gateway via Docker Compose.
Generates a gateway token and writes it to .env.

Optional environment variables:

OPENCLAW_DOCKER_APT_PACKAGES - install extra apt packages during the build
OPENCLAW_EXTRA_MOUNTS - add extra host bind mounts
OPENCLAW_HOME_VOLUME - persistence of /home/node in a named volume.

After that finishes:

Open http://127.0.0.1:18789/ in a browser.
Paste the token control into the UI (Settings → Token).
Need the URL again? docker compose run --rm openclaw-cli dashboard --no-open

It writes config/workspace on the host:

~/.openclaw/ - the configuration directory. This eventually holds OpenClaw memory, configuration, third-party API keys, and so on.
~/.openclaw/workspace - a workspace directory full of files the agent can use directly when running inside the container. Files the agent creates are also stored here.

If you want to do it manually

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

If unauthorized or disconnected (1008): pairing required is printed, you need to approve the dashboard link and the browser device:

# 대시보드 링크 재생성
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>

How to connect

If you just connect, the dashboard prints the following:

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

For security reasons, you can only connect via the localhost domain or the https:// scheme.

So you need to connect through an SSH tunnel from a terminal on your local PC:

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

Then connect to http://localhost:18789.

Registering Telegram

If you type anything in the chat room with the chatbot, the following is printed:

OpenClaw: access not configured.

Your Telegram user id: NNNNNNNN

Pairing code: XXXXXXXX

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

Run the command using the code shown.

openclaw pairing approve telegram XXXXXXXX

If you run it directly in the Docker container, use the following command:

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

wakeMode

A setting that determines how an OpenClaw cron job is executed. If not specified, next-heartbeat is the default.

Values

Value	Description	Use case
`now`	Runs immediately at the scheduled time	On-time notifications, when exact timing is needed
`next-heartbeat`	Runs at the next heartbeat after the scheduled time	Saving battery/resources, when loose timing is acceptable

How it works

now

The gateway runs the job directly at the scheduled time (e.g. 08:00)
The gateway process manages the timer
Exact execution time guaranteed

next-heartbeat

Does not run immediately even after the scheduled time has passed
Waits until the next heartbeat poll arrives
Delays can occur depending on the heartbeat interval
If heartbeat is disabled, it never runs

Caveats

next-heartbeat requires heartbeat polling to be enabled
A long heartbeat interval delays notifications
If you need on-time notifications, always use now

Example

{
  "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

When registering a device as follows:

docker compose run --rm openclaw-cli devices list

typing it prints the following error:

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)

In this case, run it directly in the gateway container:

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

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

When registering a device:

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

If the following is printed:

🦞 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)

It says token mismatch. The connection works, but authentication fails. Check the tokens in the configuration files:

# 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

All three tokens above must be identical.

If the token is lNXrjBP5su9SUP4spBfNTaEYZy67WmB7b25ex4yYeXAENSDW, you can specify the token directly as follows:

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

Register using the UUID in the Request column of the printed Pending table. If the Request UUID is 99a9713e-be0d-469f-bca4-25153a12a670:

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

Favorite site

Guides

author Zer0 sitemap