Command actions

Commands are rows in 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 calls lease_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 failed and stay that way. The UI surfaces failures; the operator re-enqueues if needed.
• Timeout. Shell commands are killed after COMMAND_TIMEOUT seconds (default 120). Auth flows have a separate 5-minute ceiling.
• Parallelism. auth_start runs in a background thread. All other actions run sequentially on the main lease loop. This ensures an auth_paste can be leased and processed while an auth_start is 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.

---

​

Credential scrubbing

The runner redacts secrets from command rows immediately after they’re used: