Skip to main content
POST
/
agent
Register agent
curl --request POST \
  --url https://api.example.com/agent \
  --header 'Content-Type: application/json' \
  --data '
{
  "action": "<string>",
  "setup_code": "<string>",
  "agent_name": "<string>"
}
'

​
Request

{
  "action": "register",
  "setup_code": "ABC123",
  "agent_name": "code-reviewer",
  "device_hostname": "macbook-pro",
  "device_os": "Darwin",
  "device_fingerprint": "abc123def456",
  "openclaw_version": "4.2.0"
}
​
action
string
required
Must be "register".
​
setup_code
string
required
A valid 6-character setup code from the dashboard.
​
agent_name
string
Human-readable name. Defaults to hostname.

​
Response

{
  "agent_id": "uuid",
  "fleet_id": "uuid",
  "bootstrap_token": "bt_...",
  "created_at": "2026-03-28T07:00:00Z"
}
The bootstrap_token is only returned once. The CLI stores it automatically in openclaw.plugin.json.

​
Errors

CodeHTTPMeaning
SETUP_CODE_INVALID404The setup code doesn’t exist. Check for typos.
SETUP_CODE_EXPIRED410Code expired (valid for 15 minutes). Generate a new one from the dashboard.
SETUP_CODE_CONSUMED410Code was already used. Generate a new one.
PLAN_LIMIT_AGENTS403Agent limit reached for your plan. Upgrade or remove unused agents.
AUTH_REQUIRED401Missing or invalid user token. Run celerflow login.
RATE_LIMITED429Too many requests. Check Retry-After header.
{
  "error": {
    "code": "SETUP_CODE_EXPIRED",
    "message": "Setup code has expired. Generate a new one from the dashboard.",
    "status": 410
  }
}