OpenClaw Onboard Command: Start Your First Agent in Minutes

Your first agent should take minutes, not hours. The openclaw onboard command delivers exactly that: a guided setup that writes your agent config, connects your model, assigns a channel, and registers everything with the gateway. Skip the manual YAML editing. This is how you do it correctly, the first time.

What the Onboard Command Actually Does

The openclaw onboard command is an interactive wizard that handles all the setup steps that typically trip up new users. Understanding what's happening under the hood helps you troubleshoot when something doesn't go as expected.

Here's the sequence onboard executes automatically:

1. Checks for an existing agent config in the current directory
2. Connects to your gateway and fetches available models from your configured providers
3. Presents an interactive selection menu for agent name, model, and channel
4. Generates the agent YAML config file with your selections
5. Registers the new agent with the gateway
6. Starts the agent process and confirms it's receiving messages

Each step that fails produces a specific error code. That matters. When you see ERR_ONBOARD_003, you know immediately it's a gateway registration failure — not a config problem, not a model issue. The error codes are your first debugging tool.

As of early 2025, openclaw onboard supports all major model providers: Anthropic, OpenAI, Google, and any OpenAI-compatible endpoint. The wizard pulls available models from your ~/.openclaw/config.yaml provider settings automatically.

Running the Onboard Command Step by Step

Before you start, make sure your gateway is running. Onboard checks the gateway connection during the registration step — if the gateway is unreachable, the command completes locally but cannot register the agent. Here's the complete flow:

# Start your gateway first (in a separate terminal)
openclaw gateway start

# Create a directory for your new agent
mkdir my-research-agent && cd my-research-agent

# Run the onboard wizard
openclaw onboard

The wizard begins immediately. You'll see a sequence of prompts:

OpenClaw Onboard Wizard v2.1.4
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

? Agent name: research-agent-01
? Select model provider: [Anthropic] [OpenAI] [Google]
? Select model: claude-3-5-sonnet-20241022
? Select channel type: [Telegram] [WhatsApp] [API only]
? Channel name/token: (paste your Telegram bot token)
? Add skills now? [web-search] [file-manager] [code-runner]
? Confirm and register? [Y/n]

✓ Config written to ./agent.yaml
✓ Agent registered with gateway (ID: agent-research-001)
✓ Agent online and receiving messages

The entire process takes under two minutes. Your agent is running before you'd finish reading a setup guide.

Sound familiar? This is the setup experience most frameworks promise but don't deliver. OpenClaw's onboard actually works because it validates each selection before moving to the next step.

Flags and Options Reference

The onboard command has a clean set of flags covering both the interactive and non-interactive usage patterns. These are the ones that matter most:

Non-Interactive Mode for Scripted Setups

If you're provisioning agents automatically — in a Dockerfile, a CI/CD pipeline, or a provisioning script — the interactive wizard gets in the way. Pass all required flags directly and onboard runs without any prompts.

# Non-interactive onboard — no prompts, suitable for scripts
openclaw onboard \
  --name research-agent-01 \
  --model claude-3-5-sonnet-20241022 \
  --channel api \
  --skills web-search,file-manager \
  --output /etc/openclaw/agents/research-01/ \
  --yes

# Verify the agent registered successfully
openclaw status --agent research-agent-01

The --yes flag is important in scripts. Without it, onboard stops and waits for confirmation if a config file already exists at the target path. In a CI pipeline, that wait causes the job to hang indefinitely.

Here's where most people stop. They run onboard, see the success message, and move on. What they miss is that onboard doesn't validate your skills installation — it queues the skills for install but doesn't confirm they loaded correctly. Always follow a scripted onboard with a status check.

Common Mistakes When Running Onboard

After watching dozens of teams set up their first OpenClaw agents, the same mistakes appear consistently. Here's what goes wrong and how to avoid it.

Not starting the gateway first. Onboard's most confusing failure mode: the command completes, writes the config, reports success — but the agent never appears online. The gateway registration silently failed because the gateway wasn't running. Always confirm openclaw gateway status shows running before you start onboard.

Running onboard from the wrong directory. The config file lands in your current working directory. If you run onboard from your home directory, the config file ends up in ~/agent.yaml mixed in with your other files. Create the agent directory first, cd into it, then run onboard.

Selecting a model that isn't provisioned. The model list shows everything in your provider config — including models you've listed but haven't added API keys for. Selecting one of these produces a cryptic provider auth error when the agent first tries to respond. Check that your API key is valid for the selected model before completing onboard.

Ignoring the skills install queue. As mentioned above, skills installs are asynchronous. A frequent issue: agent appears online, you send it a message requiring web search, and it responds that it can't perform web searches. The skill failed to install silently. Always verify with openclaw plugins list.

Using --yes in production pipelines without a pre-check. The --yes flag silently overwrites any existing agent config. In a CI pipeline that runs on every deploy, this can reset your carefully tuned production agent config back to defaults on every push. Add a conditional check before onboard runs in CI.

Frequently Asked Questions

What does openclaw onboard do?

The openclaw onboard command walks you through creating your first agent interactively. It prompts for an agent name, model selection, channel assignment, and initial skills. It then writes the agent config file and registers the agent with your gateway automatically — no manual YAML editing required.

Can I run openclaw onboard non-interactively?

Yes. Pass all required parameters as flags: --name, --model, --channel, and --skills. This lets you script agent creation in CI/CD pipelines or provisioning scripts. Non-interactive mode skips all prompts and uses the values you provide directly.

What happens if I run openclaw onboard when an agent already exists?

OpenClaw detects the existing config and asks if you want to overwrite it. Answering no aborts safely. Answering yes replaces the entire agent config. If you want to modify an existing agent, use openclaw config set instead — it updates individual fields without touching the rest.

Do I need the gateway running before I run openclaw onboard?

The gateway must be running and reachable for onboard to complete the registration step. If the gateway is down, onboard writes the config locally but cannot register the agent. Start the gateway first, then run openclaw onboard, and the agent registers and connects immediately.

Which models can I select during openclaw onboard?

Any model you have configured in your provider settings appears in the onboard model selection list. Run openclaw models to see available options before starting onboard. If no models appear, add a provider key first via openclaw config set provider.key your-api-key.

How do I add more skills after running openclaw onboard?

Use openclaw plugins install after onboarding to add skills to an existing agent. You can also edit the agent config file directly and run openclaw restart to apply changes. The onboard command is the starting point — everything can be adjusted afterward without re-running it.