Agent Spawner

Deploy a new OpenClaw agent conversationally. Official install, carry over config from the current agent. User never edits a file.

intent

Spawn a production-ready OpenClaw agent by asking the user 2-3 questions, then automating the full setup. This skill reads your current agent's config (provider, API keys, tools, plugins, skills), deploys a new agent with all that carried over, and hands you the URL and token. use this when you want to create, spin up, deploy, or provision a new OpenClaw agent without manual config edits.

inputs

Current agent environment:

• ~/.openclaw/openclaw.json - agent config file (required)
• ~/.openclaw/.env - optional env vars file
• $OPENCLAW_API_KEY, $ANTHROPIC_API_KEY, $GEMINI_API_KEY, $OPENAI_API_KEY - detected from environment
• ~/.openclaw/extensions/ - installed plugins directory
• <workspace>/skills/ - workspace skills directory

User inputs (via conversation):

• deployment target: Docker (local or remote SSH) or bare metal
• agent name: container or daemon name (auto-generated if not provided)
• optional: purpose or constraints

External connections:

• Docker daemon (if Docker deployment chosen) - must be running and accessible
• GitHub (to clone openclaw repo) - requires internet access
• LAN access (if gateway-bind set to lan) - for multi-machine setups
• SSH (if remote Docker deployment) - credentials must be configured

Rate limits / edge cases:

• API key validation happens during onboard, fails if key is invalid or expired
• port conflicts: script finds unused port starting from 18789, retries if taken
• network timeouts during docker pull: retry up to 3 times before failing
• empty skills directory: script handles gracefully, deploys with zero custom skills
• permission errors on host volume mounts: docker user must match current user uid for bind mounts

procedure

step 1: read current config (silent)

cat ~/.openclaw/openclaw.json
cat ~/.openclaw/.env 2>/dev/null
env | grep -iE 'API_KEY|TOKEN'
ls ~/.openclaw/extensions/
ls <workspace>/skills/

Identify and extract:

• provider: check auth.profiles in openclaw.json - could be Anthropic, OpenAI, Gemini, or custom
• api key: from env var or config file (e.g. ANTHROPIC_API_KEY, GEMINI_API_KEY, OPENAI_API_KEY)
• model: from agents.defaults.model field
• tool keys: all entries in tools.* (search APIs, web APIs, etc.)
• plugins: from plugins.installs array - note npm spec for each
• skills: run openclaw skills list to distinguish bundled vs workspace-only. only carry over non-bundled skills.
• heartbeat interval: from agents.defaults.heartbeat.every

output: internal state object with detected config

step 2: ask user three questions

1. "where should i deploy it?" - offer Docker (local), Docker (remote SSH host), or bare metal. wait for explicit choice.
2. "what name?" - for container or daemon. generate a random name (adjective-noun) if user says "doesn't matter".
3. "anything special?" - optional field for purpose or constraints. user can skip.

output: user responses stored. do not ask about keys, plugins, skills, ports, or config details.

step 3: confirm plan before action

Assemble and present the full deployment plan in one block:

here's the plan:

📦 deploy: Docker on <target>
📛 name: <agent-name>
🌐 port: <port>

carrying over from current agent:
  ✅ provider: Anthropic (API key)
  ✅ model: anthropic/claude-sonnet-4-20250514
  ✅ brave search api key
  ✅ plugins: openclaw-agent-reach
  ✅ skills: agent-spawner, weather
  ✅ heartbeat: 30m

the new agent will bootstrap its own identity on first message.

good to go?

only list items that actually exist in current config. wait for explicit "yes" or "proceed" before step 4. if user wants changes, ask what to adjust, modify plan, and re-confirm.

output: explicit user confirmation

step 4: deploy

4a. docker deployment (local or remote)

git clone https://github.com/openclaw/openclaw.git <agent-name>
cd <agent-name>

if remote SSH deployment, run all commands via ssh:

ssh <user>@<host> "cd /tmp && git clone https://github.com/openclaw/openclaw.git <agent-name>"

set environment variables (local or via ssh):

export OPENCLAW_IMAGE=alpine/openclaw:latest
export OPENCLAW_CONFIG_DIR=~/.openclaw-<agent-name>
export OPENCLAW_WORKSPACE_DIR=~/.openclaw-<agent-name>/workspace
export OPENCLAW_GATEWAY_PORT=<unused port, default 18789>
export OPENCLAW_GATEWAY_BIND=lan

mkdir -p $OPENCLAW_CONFIG_DIR/workspace

determine provider and api key from step 1. run non-interactive onboard:

docker compose run --rm openclaw-cli onboard --non-interactive --accept-risk \
  --mode local \
  --auth-choice <detected-provider> \
  --<provider>-api-key "$API_KEY" \
  --gateway-port $OPENCLAW_GATEWAY_PORT \
  --gateway-bind $OPENCLAW_GATEWAY_BIND \
  --skip-skills

provider flag mapping:

provider	--auth-choice	key flag
Anthropic	apiKey	--anthropic-api-key
Gemini	gemini-api-key	--gemini-api-key
OpenAI	apiKey	set OPENAI_API_KEY env var
custom	custom-api-key	--custom-api-key + --custom-base-url + --custom-model-id

start gateway:

docker compose up -d openclaw-gateway

note: onboard error about gateway connection is expected (gateway not running yet). config is still written to disk.

output: gateway running, token written to $OPENCLAW_CONFIG_DIR/openclaw.json

4b. bare metal deployment

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

run onboard with detected provider:

openclaw onboard --non-interactive --accept-risk \
  --mode local \
  --auth-choice <detected-provider> \
  --<provider>-api-key "$API_KEY" \
  --gateway-port 18789 \
  --gateway-bind lan \
  --install-daemon \
  --daemon-runtime node \
  --skip-skills

output: openclaw daemon installed and running, token in ~/.openclaw/openclaw.json

step 5: patch running agent with current config

define cli alias for easy commands:

# Docker
OC="docker compose exec openclaw-gateway node /app/openclaw.mjs"
# Bare metal
OC="openclaw"

patch config (only settings that exist in current agent):

$OC config set agents.defaults.model "<model>"
$OC config set agents.defaults.heartbeat.every "30m"
# tool keys - only if they exist in current config
$OC config set tools.web.search.apiKey "<key>"
# repeat for each tool key from step 1

install plugins (from plugins.installs in current config):

$OC plugins install <npm-spec>
# repeat for each plugin

copy workspace skills:

# Docker
docker cp <source-workspace>/skills/ <container-id>:/home/node/.openclaw/workspace/skills/
# Bare metal
cp -r <source-workspace>/skills/ ~/.openclaw/workspace/skills/

restart gateway:

# Docker
docker compose restart openclaw-gateway
# Bare metal
openclaw gateway restart

output: new agent fully configured and running

step 6: hand off to user

read gateway token:

grep -A1 '"token"' $OPENCLAW_CONFIG_DIR/openclaw.json

provide user with connection details:

• url: http://<host>:<port>/ (or https if TLS configured)
• token: (from config, auto-generated during onboard)
• next step: "say hello, it'll bootstrap itself"

output: user can access new agent

decision points

if docker deployment chosen:

• if local: deploy to localhost, use default port 18789
• if remote SSH: deploy to remote <user>@<host>, find unused port on remote, return remote URL to user

if api key not found in env or config:

• fail with error message "no api key detected for . set PROVIDER_API_KEY env var and try again"

if port 18789 is taken:

• find first unused port starting from 18790, increment until free port found, use that instead

if docker compose pull fails (network timeout):

• retry up to 3 times with 10 second backoff. if all retries fail, exit with error "docker image pull failed. check network and try again"

if plugins.installs is empty in current config:

• skip plugin install step, log "no plugins to carry over"

if workspace skills directory is empty:

• skip skills copy step, log "no custom skills to carry over"

if onboard returns auth failure (invalid api key):