---
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:

```bash
node --version
```

If below v22, upgrade via NodeSource:

```bash
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:

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

## Step 2: Install OpenClaw

```bash
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.):

```bash
openclaw onboard
```

Or for just credentials/channel configuration:

```bash
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:

```bash
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`:

```bash
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:

```bash
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:

```bash
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):

```bash
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:

```bash
openclaw devices list
```

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

```bash
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:

```bash
openclaw configure
```

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

Generate via Claude Code:

```bash
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 `{}`:

```json
"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:

```bash
grep -r "baseUrl" ~/.openclaw/
```

If found, remove the `/v1` suffix:

```diff
- "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:
```bash
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. |