---

name: openclaw-setup
description: Use when the user wants to install OpenClaw, set up OpenClaw, configure OpenClaw, run OpenClaw, or get OpenClaw working in their Adom Docker container. Covers the full setup from Node.js upgrade through gateway configuration to browser access.

OpenClaw Setup in Adom Docker

OpenClaw is an open-source AI agent (https://github.com/openclaw/openclaw). It requires special configuration to run inside an Adom Docker container because the default settings assume local desktop access. This skill walks through every step.

Step 1: Prerequisites — Node.js 22+

OpenClaw requires Node.js 22 or later. Adom containers ship with Node 18.

Check the current version:

node --version

If below v22, upgrade via NodeSource:

curl -fsSL https://deb.nodesource.com/setup_22.x -o /tmp/nodesource_setup.sh
sudo bash /tmp/nodesource_setup.sh
sudo apt-get install -y nodejs

Verify:

node --version   # should be v22.x.x
npm --version

Step 2: Install OpenClaw

sudo npm install -g openclaw@latest
openclaw --version

Step 3: Onboarding

Run the interactive setup wizard. The user must answer the prompts (model provider, API keys, channels, etc.):

openclaw onboard

Or for just credentials/channel configuration:

openclaw configure

Let the user drive this step — they need to choose their model provider and enter API keys. Do not attempt to automate the interactive wizard.

Step 4: Adom Docker Configuration

This is the critical section. The default OpenClaw config does not work in a Docker container accessed through the Adom coder proxy. Three changes are required.

4a. Allow non-loopback Control UI

The gateway refuses to serve the Control UI on non-loopback interfaces unless explicitly configured:

openclaw config set gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback true

4b. Start the gateway bound to all interfaces

The default bind mode is loopback (127.0.0.1 only). The Adom coder proxy connects from a different IP, so the gateway must bind to 0.0.0.0:

openclaw gateway run --bind lan

Run this in the background or in a separate terminal. The gateway must stay running.

4c. Construct the browser URL

The Adom coder proxy URL template is available in the VSCODE_PROXY_URI environment variable:

echo $VSCODE_PROXY_URI
# Example: https://coder.john-adom-conduit-d4d7f7f287915e49.containers.adom.inc/proxy/{{port}}/

Replace {{port}} with the OpenClaw gateway port (default: 18789).

Then read the gateway auth token:

openclaw config get gateway.auth.token

Build the full URL with both the auth token AND an explicit gatewayUrl parameter. The gatewayUrl is required because the Control UI's WebSocket must route through the proxy — without it, the UI connects but shows "Disconnected from gateway."

The format is:

https://<proxy-host>/proxy/18789/#token=<TOKEN>&gatewayUrl=wss://<proxy-host>/proxy/18789

Example (constructed programmatically):

PROXY_BASE=$(echo $VSCODE_PROXY_URI | sed 's|{{port}}|18789|')
TOKEN=$(openclaw config get gateway.auth.token 2>&1 | tr -d '"')
echo "${PROXY_BASE}#token=${TOKEN}&gatewayUrl=wss://$(echo $PROXY_BASE | sed 's|https://||;s|/proxy/.*||')/proxy/18789"

Give this URL to the user. Tell them to open it in a standalone browser tab — not in an iframe, Hydrogen viewer, or VS Code webview. OpenClaw sends X-Frame-Options: DENY and frame-ancestors 'none' headers that block iframe embedding.

Step 5: Device Pairing

When the user first opens the Control UI in their browser, OpenClaw will show "Pairing required." Approve it from the container:

openclaw devices list

This shows pending pairing requests with their Request ID. Approve the pending device:

openclaw devices approve <request-id>

The browser should then connect and show "Health OK" in the top bar.

Step 6: Auth Token Configuration

Option A: Anthropic API Key (recommended)

Get a key from https://console.anthropic.com (starts with sk-ant-api03-). Configure during openclaw onboard or set manually:

openclaw configure

Option B: Claude OAuth Token (from Max/Pro subscription)

Generate via Claude Code:

claude setup-token

Token truncation warning: The token output often wraps across two lines in the terminal. When pasting, the user MUST join both lines into a single string with no spaces or newlines. For example, if the output shows:

sk-ant-oat01-abcdef123456...firstpart
secondpart-endoftoken

The full token is sk-ant-oat01-abcdef123456...firstpartsecondpart-endoftoken (one continuous string).

If the token was entered incorrectly (truncated), fix it in these two files:

• /home/adom/.openclaw/agents/main/agent/auth.json — the key field
• /home/adom/.openclaw/agents/main/agent/auth-profiles.json — the token field

Also clear any error cooldowns in auth-profiles.json by resetting usageStats to {}:

"usageStats": {}

BaseURL double-/v1 gotcha

After OpenClaw upgrades, the Anthropic SDK may auto-append /v1/messages to the base URL. If the config still has "baseUrl": "https://api.anthropic.com/v1", requests go to /v1/v1/messages and return 404 (which can look like a 401 auth error).

Check for this in ~/.openclaw/openclaw.json and any models.json files:

grep -r "baseUrl" ~/.openclaw/

If found, remove the /v1 suffix:

- "baseUrl": "https://api.anthropic.com/v1"
+ "baseUrl": "https://api.anthropic.com"

Reference: https://github.com/openclaw/openclaw/issues/9938

Step 7: Verification

After setup, confirm everything works:

1. Gateway health:

openclaw health

2. Check the browser — the Control UI should show:

   • "Version" badge (green)
   • "Health OK" badge (green)
   • Chat input active (not "Disconnected from gateway")

3. Send a test message in the Chat tab and confirm a response comes back.

Troubleshooting

Symptom	Cause	Fix
ECONNREFUSED 0.0.0.0:18789 in browser	Gateway bound to loopback only	Start with openclaw gateway run --bind lan
refused to connect in browser	Not logged into Adom coder proxy, or wrong URL	Open the Gallia Viewer URL first (same browser) to establish the session cookie, then open the OpenClaw URL
Page loads but shows in iframe error	OpenClaw sends X-Frame-Options: DENY	Open in a standalone browser tab, not iframe/Hydrogen
UI loads, "Disconnected from gateway"	WebSocket trying to connect to wrong host	Add &gatewayUrl=wss://<proxy-host>/proxy/18789 to the URL hash
"Pairing required" in browser	New browser device needs approval	Run openclaw devices list then openclaw devices approve <id>
Gateway won't start with --bind lan	Missing allowedOrigins or fallback config	Run openclaw config set gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback true
401 authentication_error after sending a message	Token truncated (line-wrap), or double /v1 in baseUrl	Check full token in ~/.openclaw/agents/main/agent/auth.json; check grep -r baseUrl ~/.openclaw/
401 with OAuth token	Token from claude setup-token was split across lines	Join both lines into one string, update both auth.json and auth-profiles.json, reset usageStats
Gateway shows config change detected; evaluating reload	Config was updated while gateway runs	Most config changes hot-reload. For auth changes, restart the gateway.