Install OpenClaw into a user-defined path and run it in a sandbox: Docker with only a workspace directory accessible (no other host filesystem). Optional OpenSandbox on Docker can be used as the sandbox runtime for execution isolation.

.
├── deploy/                 # Docker & Compose
│   ├── docker-compose.yml  # OpenClaw + optional OpenSandbox
│   ├── Dockerfile.opensandbox  # OpenSandbox server image (used when using sandbox profile)
│   └── .env.example
├── config/                 # Config templates
│   ├── openclaw.json.template
│   └── env.template
├── script/                 # Script templates and config
│   ├── install.sh.template # Used by make config to build install.sh
│   ├── run-config.sh       # Interactive config (make config)
│   ├── gen-openclaw-json.py # Generates openclaw.json with only configured providers
│   └── openclaw             # CLI compatible with native openclaw commands
├── Makefile                # Config and install tasks
└── README.md

• Docker (20.10+)
• Docker Compose v2

Run make config (with a TTY). You will be asked for:

1. Install path and workspace path (defaults: ~/.openclaw, ~/.openclaw/workspace).
2. Which LLM provider(s) to configure: OpenAI (API key), Anthropic (API key), OpenRouter (API key), or CNB (API endpoint, repo slug, token). You can choose one or more (e.g. 1,3 for OpenAI and OpenRouter).
3. For each chosen provider, the relevant API key(s) or CNB endpoint/repo/token.
4. Gateway auth token (default: random).
5. Primary model id (e.g. openrouter/anthropic/claude-sonnet-4, cnb/auto).

Only the providers you configure are written to openclaw.json; no empty provider blocks. If you run make config without a TTY (e.g. in CI), .env is created from config/env.template if missing, and openclaw.json is generated from .env (again, only providers with credentials set are included).

Generate .env, openclaw.json, and an install script (install.sh) in the project root. When run from a terminal, make config asks which provider(s) to use (OpenAI, Anthropic, OpenRouter, CNB) and prompts only for those credentials; only those providers are written to openclaw.json.

make config
# or with custom paths:
make config INSTALL_PATH=~/.openclaw WORKSPACE_PATH=~/.openclaw/workspace

You can also edit .env manually and re-run make config to regenerate openclaw.json and install.sh from the current .env (only providers with keys set in .env are included).

Run the generated install script to install into your dir (uses the paths baked into install.sh by make config):

make install

make install runs install.sh, which moves .env and openclaw.json into the install dir, copies deploy files and the openclaw CLI into INSTALL_PATH/bin/, and pulls Docker images. If you did not run make config, make install will build install.sh with default paths and run it. You can also run the script directly: ./install.sh.

After install, use the OpenClaw CLI from INSTALL_PATH/bin/openclaw (or add it to your PATH). It supports all OpenClaw commands (CLI reference): gateway control (start/stop/status/logs), devices (list/approve/reject), dashboard (Control UI URL), and any other OpenClaw subcommand. Commands other than gateway start/stop/status/logs/update are run inside the running gateway container.

cd ~/.openclaw   # or your INSTALL_PATH

# Start / stop / status (same as native openclaw gateway)
./bin/openclaw gateway start
./bin/openclaw gateway stop
./bin/openclaw gateway status
./bin/openclaw gateway restart
./bin/openclaw gateway health

# OpenSandbox is not started by default. To run with OpenSandbox:
# OPENCLAW_PROFILE=sandbox ./bin/openclaw gateway start

# Shortcuts
./bin/openclaw status    # same as gateway status
./bin/openclaw update    # pull images and restart

Connecting to the gateway (Control UI / token / pairing): Open the gateway URL in a browser (e.g. http://localhost:18789 or http://your-host:18789). If the page shows "pairing required" or "unauthorized: gateway token missing", complete pairing by entering your gateway token in the Control UI (dashboard settings). The token is in your install dir’s .env as GATEWAY_AUTH_TOKEN (e.g. grep GATEWAY_AUTH_TOKEN ~/.openclaw/.env). Paste it in the Control UI pairing/settings step and save so your client can connect.

Device approval (this device requires gateway host approval): On the gateway host (where OpenClaw is installed), use the installed openclaw CLI:

openclaw devices list          # list pending pairing requests
openclaw devices approve <requestId>   # approve the device (or omit requestId to approve latest)

Mobile / copy dashboard URL: On the desktop (gateway host), run openclaw dashboard --no-open and copy the full URL printed (including the #token=... fragment). Open that URL on your phone or other device to connect with the token already embedded.

Or add the install bin to your PATH and run openclaw from anywhere:

export PATH="$HOME/.openclaw/bin:$PATH"
openclaw gateway start
openclaw status

make start   # same as openclaw gateway start
make stop
make check   # same as openclaw gateway status
make update

To run with OpenSandbox server (optional): OPENCLAW_PROFILE=sandbox ./bin/openclaw gateway start or make start OPENCLAW_PROFILE=sandbox. The first time you use the sandbox profile, Docker will build the OpenSandbox server image from Dockerfile.opensandbox (no pip install at container start).

• OpenClaw runs inside Docker. The container has:

  • One bind mount: WORKSPACE_PATH → /workspace (or WORKSPACE_MOUNT_PATH). This is the only host path the process can access.
  • Config and state under INSTALL_PATH/openclaw (e.g. ~/.openclaw in container).

• For safety, set WORKSPACE_PATH to a dedicated directory (e.g. INSTALL_PATH/workspace). Do not use / or a path that contains sensitive system or home directories.

• OpenSandbox (optional) provides an extra sandbox layer for code/command execution when integrated. By default only OpenClaw runs; add OPENCLAW_PROFILE=sandbox to start the OpenSandbox server as well.

Docker Hub is often unavailable or slow from mainland China. The OpenSandbox image build already defaults to a China-accessible mirror for the Python base image (dockerproxy.cn). If that fails or is slow, set PYTHON_BASE in your install dir’s .env to another mirror, then run OPENCLAW_PROFILE=sandbox openclaw gateway start again:

Mirror	Set in .env
Default (dockerproxy.cn)	(no need to set)
DaoCloud	PYTHON_BASE=docker.m.daocloud.io/docker.io/library/python:3.11-slim
Huawei SWR	PYTHON_BASE=swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/library/python:3.11-slim

When Docker Hub is reachable (e.g. outside China), you can use PYTHON_BASE=python:3.11-slim.

Variable	Description	Example
INSTALL_PATH	Install root (config, data, compose)	~/.openclaw
WORKSPACE_PATH	Host path for workspace (sandbox boundary)	~/.openclaw/workspace
WORKSPACE_MOUNT_PATH	Path inside container	/workspace
GATEWAY_PORT	Gateway port on host	18789
GATEWAY_AUTH_TOKEN	Gateway auth token	(random secret)
GATEWAY_TRUSTED_PROXIES	Comma-separated proxy IP(s) when gateway is behind a reverse proxy (clears "Proxy headers from untrusted address")	e.g. 172.18.0.1
LLM_MODEL_PRIMARY	Default model id	openrouter/anthropic/claude-sonnet-4
OPENAI_API_KEY / ANTHROPIC_API_KEY / OPENROUTER_API_KEY	Provider API keys	(set one)
CNB_API_ENDPOINT, CNB_REPO_SLUG, CNB_TOKEN	CNB provider (optional)	Fixed endpoint https://api.cnb.cool; set repo slug and token
OPENSANDBOX_PORT	OpenSandbox server port (when using sandbox profile)	8889
PYTHON_BASE	Base image for building OpenSandbox (default: China-accessible mirror; see Mainland China)	dockerproxy.cn/library/python:3.11-slim or python:3.11-slim

Target	Description
make help	Show targets and variables
make config	Interactive (TTY): prompt for provider(s) and credentials; generate .env, openclaw.json (only configured providers), install.sh. Non-interactive: create .env from template if missing, then generate from .env.
make install	Install to INSTALL_PATH (copy deploy, config, scripts)
make start	Start OpenClaw only (OpenSandbox not started by default; use OPENCLAW_PROFILE=sandbox to include it)
make stop	Stop services
make check	Show container status and gateway health
make update	Pull images and restart

Port 18789 not listening after openclaw gateway start

1. Check container state: openclaw gateway status (shows running/exited).
2. View container logs: openclaw gateway logs — look for startup errors, config or permission issues.
3. Ensure config exists: INSTALL_PATH/openclaw/openclaw.json must exist (created at install). If missing, run make config then make install again.
4. Ensure .env in the install dir has valid, absolute-style paths (or use defaults). The openclaw script expands ~ when starting.

Control UI: "origin not allowed"

The generated config sets gateway.controlUi.allowedOrigins to ["*"] so the Control UI can be opened from any host (e.g. from another machine on the LAN). Regenerate config with make config and reinstall or copy the updated openclaw.json into your install dir, then restart the gateway. If you prefer to restrict origins, edit openclaw.json and set gateway.controlUi.allowedOrigins to an array of explicit origins (e.g. ["http://localhost:18789", "http://192.168.1.5:18789"]).

"unauthorized: gateway token missing"

The client (e.g. Cursor, or the browser) must send the gateway auth token. Open the gateway URL in a browser (e.g. http://localhost:18789), open the Control UI / dashboard, go to settings, and paste your gateway token there. The token is in your install dir’s .env as GATEWAY_AUTH_TOKEN (e.g. cat INSTALL_PATH/.env | grep GATEWAY_AUTH_TOKEN).

Control UI shows "pairing required"

Complete pairing by entering your gateway token in the Control UI. Open the gateway URL in a browser, follow the pairing/settings flow on the page, and paste the value of GATEWAY_AUTH_TOKEN from your install dir’s .env (e.g. grep GATEWAY_AUTH_TOKEN ~/.openclaw/.env). Save; the client will then be paired and can connect.

Chat / API returns 403 (no body)

If you see 403 status code (no body) or logs like [agent/embedded] embedded run agent end: ... isError=true error=403 status code (no body), the request is being rejected. Two cases:

• Gateway auth – The client isn’t sending the gateway token or it’s wrong. You’ll see reason=token_mismatch or reason=token_missing in gateway logs. Fix: paste the exact GATEWAY_AUTH_TOKEN from your install dir’s .env into the Control UI / client settings and complete pairing if prompted. After pairing, use the same token the client stores.
• LLM provider (e.g. CNB) – If the Control UI is connected (webchat connected in logs) but embedded runs still get 403, the 403 may come from the model provider (e.g. CNB API), not the gateway. Check the provider’s API key, repo slug, and permissions; confirm CNB_TOKEN / repo slug in .env are correct and the token has access to the repo.

1. Send the gateway token – The client must send your gateway auth token. The token is in your install dir’s .env as GATEWAY_AUTH_TOKEN. In Cursor or another IDE, set the OpenClaw gateway URL and token in its settings and ensure the token matches exactly (no extra spaces).

2. Pair the client – Open the gateway URL, complete pairing, and save the token in the client’s settings so it sends it on every request.

3. Check gateway logs – Run openclaw gateway logs --tail=100 and look for token_mismatch, token_missing, or reason=... to see whether the failure is gateway auth or later (e.g. provider).

"Proxy headers detected from untrusted address" / trustedProxies

When the gateway is behind a reverse proxy (e.g. host=code.weilutan.com, fwd=61.144.201.234), the gateway may log this and not treat the connection as local. To fix: set gateway.trustedProxies in openclaw.json to the proxy IP(s) the gateway sees (e.g. 172.18.0.1 for Docker bridge, or your proxy’s internal IP). Regenerate config with GATEWAY_TRUSTED_PROXIES=172.18.0.1 in .env and re-run make config, or edit INSTALL_PATH/openclaw/openclaw.json and add under gateway: "trustedProxies": ["172.18.0.1"] (use the IP shown in the log as remote= or your proxy IP). Then restart the gateway.

OpenSandbox build fails: "failed to fetch anonymous token" / "connection reset by peer"

Docker Hub is often unreachable from mainland China. The Dockerfile defaults to a China-accessible mirror; see Mainland China: Docker and OpenSandbox for PYTHON_BASE options. If the default proxy fails in your region:

• Mainland China: set PYTHON_BASE in .env to one of the mirrors in the table (e.g. DaoCloud or Huawei SWR), then run OPENCLAW_PROFILE=sandbox openclaw gateway start again.

• Docker Hub reachable: set PYTHON_BASE=python:3.11-slim in .env, then start with the sandbox profile.

• Pre-build elsewhere: on a host that can pull the base image, run docker build -f Dockerfile.opensandbox -t openclaw-opensandbox:latest . in the install dir, then docker save openclaw-opensandbox:latest | gzip > opensandbox.tar.gz, copy to this host, and run docker load < opensandbox.tar.gz.

• Retry: sometimes the error is transient; try again after a few minutes.

Same as OpenClaw and OpenSandbox (see their repositories).