oc agent create <id>
Create a new agent. HTTP API →
Managed core to use (e.g.
hermes, openclaw). Required — a core-less agent has no runtime and can’t connect channels or install packages. To create a raw agent with your own snapshot, use the REST API directly.Secret
KEY=VALUE (repeatable). Secrets are stored encrypted and injected at sandbox creation.Return immediately after the agent record is created, without polling for sandbox readiness. The
async JSON field indicates the caller should re-check with oc agent get.oc agent list
List all agents. Alias: oc agent ls
HTTP API →
Output columns: ID, CORE, CHANNELS, PACKAGES, CREATED
oc agent get <id>
Show detailed information for an agent, including instance status. HTTP API →
Output: ID, Name, Core, Channels, Packages, Created, Instance (ID + status).
oc agent delete <id>
Delete an agent. Cascades to instances and sessions — the sandbox is destroyed. HTTP API →
Skip the confirmation prompt. Required when stdin is not a TTY (e.g. running from a script) — the command otherwise refuses rather than destroying state silently on a typo.
oc agent connect <id> <channel>
Connect a messaging channel to an agent. HTTP API →
Telegram bot token (Telegram channel only). If omitted and stdin is a TTY, the CLI prompts interactively. If omitted and stdin is not a TTY (scripts, CI, agent callers), the command exits with an error — pass the flag explicitly.
oc agent disconnect <id> <channel>
Disconnect a channel from an agent. Removes webhook registration and config. HTTP API →
Skip the confirmation prompt. Required when stdin is not a TTY.
oc agent channels <id>
List channels connected to an agent. HTTP API →
oc agent install <id> <package>
Install a package on an agent. HTTP API →
oc agent uninstall <id> <package>
Uninstall a package from an agent. Data is preserved by default. HTTP API →
Skip the confirmation prompt. Required when stdin is not a TTY.
oc agent packages <id>
List packages installed on an agent. HTTP API →
Exit codes
oc agent commands use a class-based exit code scheme so scripts and agent callers can branch on failure type without parsing stderr.
| Code | Class | Meaning |
|---|---|---|
| 0 | Success | Command completed successfully |
| 1 | General error | Unclassified failure, bad args/flags, aborted confirmation |
| 3 | Upstream 4xx | Not found, unauthorized, org mismatch, bad request |
| 4 | Conflict | Already exists, invalid state transition |
| 5 | Transient | Timeout, retry-safe — try again |
create, install, and get when the failure carries a known error code. Other subcommands exit 0 on success and 1 on any failure.