agent_commands. Each row has an action field that tells the runner daemon what to do. There are two categories:
- Shell actions — mapped to a shell script/binary and run synchronously. The runner captures stdout/stderr and exit code.
- Connection actions (
auth_*) — interactive OAuth/API-key flows that need long-lived processes and intermediate progress updates.
Shell actions
provision
Create a new agent: runs ~/add-agent.sh which creates a git branch, checks out a template, and registers the agent with OpenClaw.
Before executing, the runner forces a sync_secrets() call to ensure the agent’s per-agent .env file is written to disk with any channel tokens that were stored in the secrets table by the UI.
Channel tokens (Telegram, Discord, Slack) are not in the payload. They are stored encrypted in the
secrets table and delivered to the gateway via the secrets sync daemon. The add-agent.sh script reads them from ~/.openclaw/secrets/agents/<slug>.env.
approve_pairing
Approve a pending channel pairing code. Runs openclaw pairing approve <channel> <code>.
update
Pull the latest commits for one agent’s branch. Runs ~/update-agent.sh <workspace-slug>/<agent-slug>.
No payload fields required beyond agent_slug on the command row.
remove
Remove an agent: unregisters from OpenClaw and deletes the git branch. Runs ~/remove-agent.sh <branch>.
No payload fields required beyond agent_slug on the command row.
update_all
Update every agent on this gateway. Runs ~/update-all-agents.sh.
No payload fields.
restart_gateway
Restart the gateway process. Behavior depends on RUNTIME_MODE:
No payload fields.
restart_dispatcher
Restart the inbox dispatcher daemon. Behavior depends on RUNTIME_MODE:
No payload fields.
update_gateway
Pull and restart the full gateway stack. Behavior depends on RUNTIME_MODE:
No payload fields.
set_agent_model
Change an agent’s default model and/or thinking level at runtime. Updates the agent’s OpenClaw config without a full gateway restart.
At least one of
model or thinking must be provided. The runner updates the agent’s agent.json config and reloads the session.
list_models
Query available models from connected providers. The runner calls openclaw models status --json and writes the result to stdout.
Connection actions (auth_*)
OAuth flows and provider API keys use these actions. They can’t follow the standard shell-command shape because they need long-lived processes, intermediate progress updates, and stdin pipes for paste-back.
The runner maintains an in-memory registry of in-flight auth sessions. If the runner restarts mid-flow, the session is lost and the user must retry — flows are short (5 min max) and runner restarts are rare.
auth_set_api_key
Add a provider using a direct API key. No interactive flow required.
After success,
api_key and base_url are scrubbed from the payload (api_key_scrubbed: true, base_url_applied: true).
auth_start
Begin an interactive OAuth or device-code login. This action runs asynchronously in a background thread so the main command loop stays responsive (and can process the auth_paste that completes the flow).
Progress states — written to
agent_commands.payload.connection_state as the flow advances:
If
NETWORKING_MODE=local and mode=oauth_paste, the runner allows OpenClaw’s built-in localhost:1455 callback to catch the OAuth redirect automatically (autoCallback: true in the state). Otherwise the runner pre-occupies port 1455 to force the paste-back path, and the UI prompts the user to paste the redirect URL into the auth_paste command.
The flow times out after 5 minutes.
auth_paste
Submit the OAuth redirect URL or code that the user pasted. This completes a running auth_start flow.
After success,
value is scrubbed (value_scrubbed: true).
auth_list
Probe all configured provider profiles and return their health. The runner calls openclaw models status --json --probe and writes the JSON output to stdout on the command row. The UI reads stdout to render the connections list.
No payload fields.
auth_refresh
Probe one specific profile (or all profiles) for current health.
auth_remove
Delete a provider profile from the auth store across all agent directories.
Edits
auth-profiles.json directly since OpenClaw doesn’t ship a delete subcommand.
auth_set_default
Set the default provider/model for this gateway.
Lease and timeout semantics
The runner callslease_command(p_gateway_slug, p_lease_seconds) to atomically claim each command. The lease duration is COMMAND_TIMEOUT + 60 seconds — long enough that the command won’t be visible to other runners before it finishes, even at the edge of the timeout.
- No auto-retry. Failed commands are marked
failedand stay that way. The UI surfaces failures; the operator re-enqueues if needed. - Timeout. Shell commands are killed after
COMMAND_TIMEOUTseconds (default 120). Auth flows have a separate 5-minute ceiling. - Parallelism.
auth_startruns in a background thread. All other actions run sequentially on the main lease loop. This ensures anauth_pastecan be leased and processed while anauth_startis waiting for user input.
Source actions
source_write
Execute a write operation against an external source connection. Requires the connection’s writable flag to be enabled.
The runner looks up the connection, verifies
writable = true, loads the provider’s ACTION_PROVIDER from the connector registry, resolves credentials from the gateway’s secrets .env file, and calls execute(action, params, creds). Results are written to the command’s stdout.