Principle:Openclaw Openclaw Container Onboarding

Knowledge Sources	OpenClaw
Domains	Deployment, Docker
Last Updated	2026-02-06 12:00 GMT

Overview

Container onboarding is the concept of running the interactive setup wizard inside containers, adapting the onboarding flow for containerized execution with volume-mounted config persistence and Docker-specific flags.

Description

OpenClaw requires initial configuration before the gateway can serve requests: selecting an AI provider, configuring authentication, setting up gateway bind mode and tokens, and optionally connecting messaging channels. On bare-metal or native installs, this is a fully interactive terminal wizard. Inside Docker containers, the onboarding must account for the ephemeral nature of the container filesystem, the need for TTY passthrough, and deployment-specific constraints.

The onboardCommand function supports two execution modes relevant to Docker. In interactive mode, the Docker Compose CLI service is invoked with stdin_open: true and tty: true, allowing the user to walk through the wizard prompts. The --no-install-daemon flag is passed because the container manages the gateway process directly (via CMD or Compose command) rather than through a system daemon. In non-interactive mode (--non-interactive), all configuration is provided via command-line flags, enabling fully automated CI/CD deployments.

Configuration written during onboarding is persisted to the volume-mounted state directory, so it survives container restarts. The function also handles Windows detection warnings, legacy auth choice migration, risk acknowledgement for non-interactive runs, and optional config resets.

Usage

Apply this concept when setting up a new OpenClaw Docker deployment (first-time onboarding), re-onboarding after a config reset, or automating deployment in CI/CD pipelines. The onboard command is the mandatory first step before the gateway can start successfully in non---allow-unconfigured mode.

Theoretical Basis

The onboarding flow inside containers follows this decision tree:

1. Runtime guard: Verify Node.js runtime compatibility via assertSupportedRuntime.
2. Auth normalization: Migrate deprecated auth choices (oauth to setup-token, claude-cli to setup-token, codex-cli to openai-codex).
3. Risk acknowledgement: Non-interactive mode requires --accept-risk to proceed, preventing accidental automated deployments without explicit consent.
4. Optional reset: If --reset is passed, clear existing configuration and workspace before onboarding.
5. Mode dispatch:
   • Non-interactive: Call runNonInteractiveOnboarding with all options provided via flags. Suitable for Dockerfiles, CI scripts, and automated cloud deployments.
   • Interactive: Call runInteractiveOnboarding with TTY prompts. Used by docker-setup.sh via docker compose run --rm openclaw-cli onboard --no-install-daemon.

The key Docker-specific adaptation is the installDaemon option (controlled by --no-install-daemon): inside a container, the gateway runs as the container's main process, so installing a system daemon (launchd, systemd) is both unnecessary and impossible.

Related Pages

Implemented By

• Implementation:Openclaw_Openclaw_OnboardCommand_Docker