> ## Documentation Index > Fetch the complete documentation index at: https://docs.yourhq.ai/llms.txt > Use this file to discover all available pages before exploring further. # Command actions > Every action the UI can dispatch to a gateway, with payload schemas and auth flow details. 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. | Field | Type | Required | Description | | ---------------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------- | | `channel` | string | No | `telegram` / `discord` / `slack` / `none`. Default `telegram` | | `discord_server_id` | string | No | Discord guild ID | | `discord_user_id` | string | No | Discord user ID for DM fallback | | `model` | string | No | Full model ID (e.g. `anthropic/claude-sonnet-4-6`). Sets the agent's default model at provision time | | `source_template` | string | No | Git branch name to copy from (e.g. `template/researcher`) | | `name` | string | No | Display name | | `description` | string | No | Short description | | `emoji` | string | No | Emoji avatar | | `owner_name` | string | No | Workspace owner's full name (for agent context) | | `owner_preferred_name` | string | No | Owner's preferred first name | | `owner_timezone` | string | No | Owner's timezone (e.g. `America/New_York`) | 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/.env`. *** ### `approve_pairing` Approve a pending channel pairing code. Runs `openclaw pairing approve `. | Field | Type | Required | Description | | -------------- | ------ | -------- | ---------------------------------------------------- | | `pairing_code` | string | Yes | The code the user received in the channel | | `channel` | string | No | `telegram` / `discord` / `slack`. Default `telegram` | *** ### `update` Pull the latest commits for one agent's branch. Runs `~/update-agent.sh /`. 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 `. 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`: | `RUNTIME_MODE` | Command | | ------------------ | ----------------------------------------------------- | | `docker` (default) | `docker compose -p restart gateway` | | `systemd` | `openclaw gateway restart` | No payload fields. *** ### `restart_dispatcher` Restart the inbox dispatcher daemon. Behavior depends on `RUNTIME_MODE`: | `RUNTIME_MODE` | Command | | -------------- | -------------------------------------------------------- | | `docker` | `docker compose -p restart dispatcher` | | `systemd` | `systemctl --user restart hq-inbox-dispatcher` | No payload fields. *** ### `update_gateway` Pull and restart the full gateway stack. Behavior depends on `RUNTIME_MODE`: | `RUNTIME_MODE` | Command | | -------------- | ------------------------------------------------------------------ | | `docker` | `docker compose -p pull && docker compose up -d` | | `systemd` | `cd ~ && git pull && ./install.sh --update` | 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. | Field | Type | Required | Description | | ------------ | ------ | -------- | -------------------------------------------------------------------------- | | `agent_slug` | string | Yes | The agent's slug | | `model` | string | No | Full model ID (e.g. `anthropic/claude-sonnet-4-6`, `openai-codex/gpt-5.4`) | | `thinking` | string | No | Thinking level: `none`, `low`, `medium`, `high` | 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`. | Field | Type | Required | Description | | ---------- | ------ | -------- | ---------------------------------------------------------------------- | | `provider` | string | No | Filter to one provider. If omitted, all connected providers are listed | *** ## 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. | Field | Type | Required | Description | | -------------- | ------ | -------- | -------------------------------------------------- | | `provider` | string | Yes | Provider ID (e.g. `openai`, `anthropic`, `gemini`) | | `api_key` | string | Yes | The API key | | `profile_name` | string | No | Profile slot. Default `default` | | `base_url` | string | No | Custom endpoint URL (for local/Ollama providers) | 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). | Field | Type | Required | Description | | -------------- | ------ | -------- | ---------------------------------------- | | `provider` | string | Yes | Provider ID | | `profile_name` | string | No | Profile slot. Default `default` | | `mode` | string | No | `oauth_paste` (default) or `device_code` | **Progress states** — written to `agent_commands.payload.connection_state` as the flow advances: | Stage | When | | ----------- | ------------------------------------------------------------------ | | `starting` | Flow just kicked off | | `url_ready` | OAuth URL detected — UI should show it for the user to click | | `polling` | Device-code flow — URL + code ready, waiting for user to authorize | | `completed` | Success — `profileId` field contains `provider:profile_name` | | `failed` | Error or timeout — `error` field contains the reason | 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. | Field | Type | Required | Description | | ------------------- | ------ | -------- | ------------------------------------------ | | `parent_command_id` | string | Yes | The `id` of the `auth_start` command row | | `value` | string | Yes | The full redirect URL or verification code | 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. | Field | Type | Required | Description | | ------------ | ------ | -------- | -------------------------------------------------------------------- | | `profile_id` | string | No | Format: `provider:profile_name`. If omitted, all profiles are probed | *** ### `auth_remove` Delete a provider profile from the auth store across all agent directories. | Field | Type | Required | Description | | ------------ | ------ | -------- | ---------------------------------------------------------- | | `profile_id` | string | Yes | Format: `provider:profile_name` (e.g. `anthropic:default`) | Edits `auth-profiles.json` directly since OpenClaw doesn't ship a delete subcommand. *** ### `auth_set_default` Set the default provider/model for this gateway. | Field | Type | Required | Description | | -------------- | ------ | -------- | ------------------------------- | | `provider` | string | Yes | Provider ID | | `profile_name` | string | No | Profile slot. Default `default` | *** ## 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. | Field | Type | Required | Description | | --------------- | ------ | -------- | -------------------------------------------------------- | | `connection_id` | string | Yes | The source connection ID | | `action` | string | Yes | Provider-specific action name (e.g. `create_page`) | | `params` | object | Yes | Action parameters (schema varies by provider and action) | 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: | Action | Fields scrubbed | | ------------------ | --------------------- | | `provision` | All `*_token` fields | | `auth_set_api_key` | `api_key`, `base_url` | | `auth_paste` | `value` |