From openclaw-config
Guide for configuring OpenClaw — a self-hosted personal AI gateway — installed via Docker. Use this skill whenever the user asks about: setting up OpenClaw with Docker, configuring openclaw.json, adding messaging channels (Telegram, Discord, WhatsApp, etc.), setting AI provider API keys, adjusting gateway settings (port, bind, auth), troubleshooting an OpenClaw Docker container, updating OpenClaw, or enabling sandbox/extensions. Trigger even if the user just says "openclaw" without an explicit config request — they almost certainly need guidance on configuration.
How this skill is triggered — by the user, by Claude, or both
Slash command
/openclaw-config:openclaw-configThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
OpenClaw is a self-hosted personal AI gateway that runs as a Docker container. It connects messaging platforms (Telegram, Discord, WhatsApp, Signal, iMessage, Slack, MS Teams) to AI providers (Anthropic, OpenAI, OpenRouter, Ollama, DeepSeek, vLLM, etc.).
OpenClaw is a self-hosted personal AI gateway that runs as a Docker container. It connects messaging platforms (Telegram, Discord, WhatsApp, Signal, iMessage, Slack, MS Teams) to AI providers (Anthropic, OpenAI, OpenRouter, Ollama, DeepSeek, vLLM, etc.).
ghcr.io/openclaw/openclaw (tags: main, latest, <version>)git clone https://github.com/openclaw/openclaw.git
cd openclaw
./docker-setup.sh
To use a pre-built image instead of building locally (faster):
export OPENCLAW_IMAGE=ghcr.io/openclaw/openclaw:main
./docker-setup.sh
The setup script builds the image, runs the interactive onboarding wizard, and starts the gateway daemon.
| Service | Purpose |
|---|---|
openclaw-gateway | Main daemon — port 18789 |
openclaw-cli | Management CLI — run one-off commands |
All management commands use:
docker compose run --rm openclaw-cli <command>
~/.openclaw/openclaw.jsonThe primary config file is ~/.openclaw/openclaw.json, written in JSON5 format (allows comments and trailing commas). It is mounted into the container at /home/node/.openclaw/openclaw.json.
{
"meta": { /* version/timestamps, managed by openclaw */ },
"gateway": { /* port, bind, auth */ },
"agents": { /* model defaults, concurrency, workspace */ },
"models": { /* provider API keys and model specs */ },
"channels": { /* messaging platform integrations */ },
"skills": { /* skill/plugin system */ },
"cron": { /* scheduled tasks */ },
"tools": { /* tool config */ },
"session": { /* conversation history/context */ },
"env": { /* inline env var definitions */ }
}
Controls how the daemon listens and authenticates.
"gateway": {
"port": 18789,
"mode": "local",
"bind": "loopback", // "loopback" = 127.0.0.1 only (safe default)
// "lan" = all interfaces (needed for LAN access)
"auth": {
"mode": "token", // token-based auth
"allowTailscale": true // allow Tailscale device auth
}
}
Security: Keep
bindset to"loopback"unless you specifically need LAN or remote access. Never expose port 18789 directly to the public internet. The gateway token (stored in~/.openclaw/.env) should be treated like a password.
To change bind mode via CLI:
docker compose run --rm openclaw-cli config set gateway.bind lan
docker compose run --rm openclaw-cli config get gateway.bind
API keys go in the models.providers section. Use environment variable interpolation (${VAR_NAME}) to keep secrets out of the config file.
"models": {
"providers": {
"anthropic": { "apiKey": "${ANTHROPIC_API_KEY}" },
"openai": { "apiKey": "${OPENAI_API_KEY}" },
"openrouter": { "apiKey": "${OPENROUTER_API_KEY}" }
}
}
Environment variables are resolved in this order:
./.env (current working directory)~/.openclaw/.env ← recommended place for secretsenv block inside openclaw.jsonRecommended: put API keys in ~/.openclaw/.env:
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
Controls which model runs tasks and how many can run at once.
"agents": {
"defaults": {
"model": {
"primary": "anthropic/claude-sonnet-4-5",
"fallbacks": ["openai/gpt-4o", "anthropic/claude-haiku-3-5"]
},
"workspace": "~/.openclaw/workspace",
"maxConcurrent": 4,
"subagents": { "maxConcurrent": 8 },
"contextTokens": 128000
}
}
# Telegram
docker compose run --rm openclaw-cli channels add --channel telegram --token "<BOT_TOKEN>"
# For other channels, omit --token to enter interactive setup:
docker compose run --rm openclaw-cli channels add --channel discord
"channels": {
"telegram": {
"token": "${TELEGRAM_BOT_TOKEN}"
// additional policies configurable here
},
"discord": {
// guild-specific settings
}
}
# Check gateway status
docker compose run --rm openclaw-cli status
# Open the web dashboard (get URL + token)
docker compose run --rm openclaw-cli dashboard --no-open
# View logs
docker compose logs openclaw-gateway
docker compose logs openclaw-gateway --tail 100
# Restart the gateway
docker compose restart openclaw-gateway
# Health check
curl -fsS http://127.0.0.1:18789/healthz
# Diagnose configuration problems
docker compose run --rm openclaw-cli doctor
docker compose run --rm openclaw-cli doctor --fix
# Device/pairing management
docker compose run --rm openclaw-cli devices list
docker compose run --rm openclaw-cli devices approve <requestId>
# Stop everything
docker compose down
# Stop and remove volumes (full reset)
docker compose down -v
These are set in your shell before running ./docker-setup.sh or docker compose:
| Variable | Purpose |
|---|---|
OPENCLAW_IMAGE | Use a pre-built remote image (skip local build) |
OPENCLAW_SANDBOX | Enable Docker-in-Docker agent sandbox (1 or true) |
OPENCLAW_EXTRA_MOUNTS | Extra bind mounts, comma-separated (e.g. $HOME/.ssh:/home/node/.ssh:ro) |
OPENCLAW_HOME_VOLUME | Persist /home/node in a named Docker volume |
OPENCLAW_DOCKER_SOCKET | Override Docker socket path |
OPENCLAW_EXTENSIONS | Space-separated list of extensions to pre-install |
OPENCLAW_DOCKER_APT_PACKAGES | Additional apt packages to install at build time |
Example with sandbox and extra mounts:
export OPENCLAW_IMAGE=ghcr.io/openclaw/openclaw:main
export OPENCLAW_SANDBOX=1
export OPENCLAW_EXTRA_MOUNTS="$HOME/.ssh:/home/node/.ssh:ro,$HOME/projects:/home/node/projects:rw"
./docker-setup.sh
cd openclaw
git pull
./docker-setup.sh
This rebuilds the image and restarts the gateway with the latest code.
| Symptom | What to try |
|---|---|
| Gateway won't start | docker compose logs openclaw-gateway — check for port conflicts or missing env vars |
| Can't reach dashboard | Check gateway.bind — must be "lan" for non-localhost access |
| API calls failing | Verify API keys in ~/.openclaw/.env; check provider name matches exactly |
| Channel not responding | Re-run channels add; verify bot token is valid |
| General config issues | docker compose run --rm openclaw-cli doctor --fix |
Permission errors on ~/.openclaw | Ensure the directory is owned by your user: chown -R $USER ~/.openclaw |
npx claudepluginhub elvinouyang/claude-skill-collection --plugin openclaw-configAnswers OpenClaw questions on configuration, troubleshooting, setup, architecture, features, channels, gateway, automation, models, and design decisions using clawdocs and openclaw CLIs.
Installs, configures, troubleshoots, and manages OpenClaw AI gateway across 23+ messaging platforms including Slack, WhatsApp, Telegram, Discord, and Teams.
Administers OpenClaw instances across macOS, Ubuntu/Debian, Docker, OCI, and Proxmox. Handles installation, gateway lifecycle, host administration, security hardening, monitoring, backups, channel config, Tailscale, and gogcli.