Skip to content

commands-and-troubleshooting.md

Latest commit

 

History

History
188 lines (130 loc) · 4.69 KB

commands-and-troubleshooting.md

File metadata and controls

188 lines (130 loc) · 4.69 KB

Commands + troubleshooting (quick reference)

Table of contents (Explain OpenClaw)

This is a copy/paste oriented page. For deeper explanations, use the official docs linked below.

Install + onboard

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

Docs: https://docs.openclaw.ai/install and https://docs.openclaw.ai/start/wizard

Non-interactive custom provider onboarding

export CUSTOM_API_KEY="your-api-key-here"
openclaw onboard --non-interactive --install-daemon \
  --custom-base-url "https://llm.example.com/v1" \
  --custom-model-id "my-model" \
  --custom-compatibility openai

Flags: --custom-base-url (required), --custom-model-id (required), --custom-api-key (optional, env var preferred), --custom-provider-id (optional), --custom-compatibility openai|anthropic (optional).

Auto-inference: providing any --custom-* flag auto-sets --auth-choice custom-api-key.

Docs: https://docs.openclaw.ai/start/wizard-cli-automation and https://docs.openclaw.ai/cli/onboard

Start/stop the Gateway

Foreground:

openclaw gateway
# alias:
openclaw gateway run

Service lifecycle:

openclaw gateway status
openclaw gateway restart
openclaw gateway stop
openclaw gateway start

Docs: https://docs.openclaw.ai/gateway and https://docs.openclaw.ai/cli/gateway

Health and status

openclaw status
openclaw status --all
openclaw health
openclaw config validate              # validate config before startup
openclaw config file                  # print active config file path

HTTP health probe endpoints (for Docker/Kubernetes): GET /health, /healthz, /ready, /readyz.

Security audit

openclaw security audit
openclaw security audit --deep
openclaw security audit --fix

Docs: https://docs.openclaw.ai/gateway/security

Pairing (DM approvals)

openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

Docs: https://docs.openclaw.ai/start/pairing

Remote access (SSH tunnel)

ssh -N -L 18789:127.0.0.1:18789 user@gateway-host

Docs: https://docs.openclaw.ai/gateway/remote

Backup + restore

openclaw backup create                        # full backup
openclaw backup create --no-include-workspace # config + state only
openclaw backup create --only-config          # just the config file
openclaw backup verify ./backup.tar.gz        # validate archive

Run openclaw backup create before openclaw reset or openclaw uninstall.

Docs: https://docs.openclaw.ai/cli/backup

Side questions (/btw)

/btw what are we doing right now?
/btw summarize the current task

Ephemeral side question against the current session — no tool calls, no transcript persistence.

Docs: https://docs.openclaw.ai/tools/btw

Common problems

Control UI says unauthorized

  • Run openclaw dashboard and open the printed tokenized URL.
  • Ensure you are connecting to the correct Gateway instance/profile.

Docs: https://docs.openclaw.ai/help/faq

Port already in use (18789)

  • Stop the supervised service (openclaw gateway stop) or choose another port.
  • Foreground reclaim: openclaw gateway --force.

Docs: https://docs.openclaw.ai/help/faq

Nothing responds in Telegram/WhatsApp

  • Check channel status and logs.
  • Confirm pairing/allowlists aren’t blocking.
  • Confirm model auth is present on the gateway host.

Docs: https://docs.openclaw.ai/help/faq and https://docs.openclaw.ai/channels/troubleshooting

High-signal official docs