OpenClaw EnterpriseDOCSGitHub

Agents

An Agent is a named AI workload in a Namespace. It has its own identity, Agent revision history, and gateway. Its permissions do not grant access across Namespaces.

Use a Preset to copy launch settings into an Agent draft.

Set up an OpenShell Codex Agent, choose Compute, manage versions, or troubleshoot deployment.

Creation saves identity and exact Namespace-owned Configuration with active status and stopped desired runtime state. No Agent revision is created and no workload or model starts until an authorized caller requests deployment.

Supported operations

Operations beneath /namespaces/:namespaceId/agents return 201 for creation, 200 for reads/updates, and 202 for deployment, stop, or deletion. Deployment returns the saved Agent revision (AgentRevision). Stop sets desiredRuntimeState to stopped. Lists require each Agent's exact read. See API schemas, envelopes, and permissions.

Responses include immutable servicePrincipalId for Namespace IAM bindings. Do not derive it from the Agent ID; create/update reject caller-supplied values.

Creation body:

json
{  "name": "ticket-triage",  "configurationId": "cfg_123e4567-e89b-42d3-a456-426614174000",  "executionMode": "dedicated",  "backendId": null}

Creation requires a provisioning or ready Namespace, a same-Namespace Configuration with kind: "agent", Namespace Agent create, and exact Configuration read. See Harness authentication for credential permissions and authorization for grants.

Unreadable saved settings

Agent list/detail and revision detail GETs omit unreadable saved settings without defaults, keep readable metadata and siblings, and add configurationReadError with code: "SAVED_CONFIGURATION_UNREADABLE" and the affected field. Revision summaries have no error field: they preserve the recorded Harness identity, version and mode, omitting overrides or resolved configuration when those settings were not recorded. Opening such a revision returns the metadata-only detail response. Authorization and strict mutation/runtime validation are unchanged; query failures still fail requests. See the Console warning.

Deployment status

The deploymentId is the saved AgentRevision ID from POST /namespaces/:namespaceId/agents/:agentId/deploy. A 202 confirms that OCC saved and queued the version. It does not confirm workload readiness. Poll with:

text
GET /namespaces/:namespaceId/agents/:agentId/deployments/:deploymentId

This requires exact AgentRevision read, not Agent operate. Responses include deploymentId, namespaceId, agentId, status, nullable error, plugin warnings, nullable progress, and nullable cleanup.

Pending progress.lastAttempt contains the latest exact-work result's allowlisted code, fixed message, and at; repeated deferrals record once, except refused-candidate stops. Null means no bound evidence. Maintenance and cleanup results are excluded. progress.nextAttemptAt is the earliest queued eligibility, not a promised start; null while claimed. Terminal progress is null. Results describe recorded checks, not runtime health.

Nullable cleanup reports retirement’s status (same meanings) and queued nextAttemptAt. Deployment failure remains terminal. Terminal preparation errors retain error.data.preparation under schema limits (identities, reasons, scheduling, exits, timestamps), excluding raw output and credentials.

Errors have fixed codes, messages, and allowlisted error.data. Each message names the cause and the next step. The console offers Deploy again only for codes that a new deployment can clear, such as DEPENDENCY_UNAVAILABLE or EXECUTION_ADMISSION_UNAVAILABLE. A version stored inconsistently (INVALID_TARGET, INVALID_REVISION_OWNER, INVALID_ADMITTED_REVISION, INVALID_ACTIVE_REVISION) has no runtime logs; ask an Installation administrator. CONVERGENCE_DEADLINE_EXCEEDED data includes timeoutMs and optional runtimeFailure (component, check, checkedAt, code) from that version (unknown values read UNRECOGNIZED); missing evidence leaves the cause unspecified. Held failures end deployment early: RUNTIME_AUTHENTICATION_FAILED (rejected credential), RUNTIME_CPU_STARVED, RUNTIME_MODEL_PROBE_TIMEOUT, RUNTIME_MODEL_PROBE_FAILED, RUNTIME_LOGIN_FAILED, RUNTIME_STARTUP_FAILED, or WORKSPACE_SETUP_REFUSED; fix and redeploy. A dedicated gateway that refuses its own CLI fails with AGENT_GATEWAY_UNAUTHORIZED. RUNTIME_MODEL_PROBE_FAILED adds runtimeFailure. Success can include plugin warnings with a closed code and pluginId.

Polling reads only persisted state. Terminal results survive runtime deletion and controller restart; later deployments cannot rewrite them.

Current runtime diagnostics

A bodyless POST to /namespaces/:namespaceId/agents/:agentId/deployments/:deploymentId/diagnostics requests fresh checks for the specified Agent revision ID. It requires Agent read and operate plus AgentRevision read. It returns an Agent revision ID, observation time, and at most 32 checks. Kubernetes reports held startup failures and probes Slack configuration, authentication, and connectivity without sending. Missing Pods yield unknown; unavailable evidence yields 503. The call changes no stored state and proves no model response. On OpenShell the agent check is always unknown; use deployment status and Harness logs. See the diagnostics flow.

Backend association

An Agent can reference one Installation-configured experimental Backend through backendId, a nullable reference returned on Agent and AgentRevision responses. Create/PATCH omission, null, and ID validation follow the association rules; no default is inferred.

The reference is independent of native model names and Harness selection. OpenAI or Anthropic API keys and directly supplied service account tokens need no Backend. An OCE-issued ChatGPT account token requires the matching Backend and account at deployment request and again before startup. Creating an Agent does not create a provider account or issue credentials.

Harness authentication

harnessAuth selects how an Agent obtains model credentials. Creation omission stores null; PATCH omission preserves the binding and explicit null clears it. Both supported topologies require a valid binding at deployment. A managed source must belong to the Agent's exact Namespace:

json
{  "harnessAuth": {    "method": "api_key",    "source": {      "kind": "secret",      "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000",      "id": "sec_123e4567-e89b-42d3-a456-426614174000"    }  }}

For a service account token, use "method": "codex_pat" with its Secret source. This requires dedicated Codex.

Personal Codex OAuth device login is Experimental. Bind the returned credential source with { "method": "credential_source", "sourceId": "cs_…" }.

For an already issued ChatGPT account credential, use { "method": "codex_pat", "source": { "kind": "service_account", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000", "id": "sa_123e4567-e89b-42d3-a456-426614174000" } }. This requires dedicated Codex and the account's matching backendId. Binding an account does not issue its credential or change the model, Harness, or Backend.

Development upgrade limitation: migration 0049 rejects retained chatgpt_service_account bindings in Agent drafts, any historical AgentRevision, or provisioning plans, and rolls back without converting them. No API deletes a Agent revision or provisioning request on its own: delete each affected Agent, which also deletes its Agent revisions and requests, and create it again after the upgrade. Changing the binding does not clear historical Agent revisions. For a request that never created an Agent, see clear legacy bindings.

For dedicated Codex with a Credential Gateway, use { "method": "credential_source", "sourceId": "cs_…" }; see credential sources for grants. It must also be listed in credentialSources.

For SSH embedded OpenClaw, use { "method": "runtime" }. The operator supplies credentials in the protected host environment file; OCC neither reads nor delivers them and performs no authentication or model probe, so readiness does not prove model access. The snapshot records only the method, so host credential changes can affect existing versions. Agent and Configuration authorization, topology checks, and process readiness remain required; no credential-source permission is needed. Kubernetes and Docker reject this method. See SSH credentials.

API-key and imported PAT bindings require the actor's exact Secret operate. That includes the Secret the Agent already uses: every draft update checks it, including one that replaces it. Deployment also requires the Agent service principal's exact Secret operate. Managed PAT binding requires the actor's exact account read, including the current account on every draft update. There is no implied account grant for the Agent principal. Each consumer of a shared source is authorized independently.

Deployment freezes binding references; dispatch rechecks source ownership and actor/Agent grants. Draft changes take effect only on deployment. Public responses omit credential values and private backend/account metadata. See supported providers, topologies, and credential delivery and Secret consumption grants.

Plugin selections

An Agent can own an optional plugins map keyed by qualified curated catalog ID, such as google-calendar@openai-curated-remote. Omission at creation enables no plugins. PATCH omission preserves the saved plugin map, {} clears every desired plugin, and a nonempty map replaces the entire desired plugin set.

Create/update validates only structural shape. Catalog membership, native identity resolution, and approval-policy support are checked when deployment starts the version; unsupported selections fail that startup without partially mutating the Agent. AgentRevision snapshots retain the requested plugin IDs and policy. See Agent plugins for field semantics and the selected-only runtime contract.

Workspace files

An Agent's workspace holds AGENTS.md, SOUL.md, IDENTITY.md, and USER.md. See Agent workspace files for request shapes, limits, permissions, and errors.

Initial contents at creation

Creation accepts optional initialWorkspaceFiles and workspaceDefaultsId. First deployment applies them once; pending inputs have no read/update API. See initial contents.

Live file access

GET and PUT on /namespaces/:namespaceId/agents/:agentId/workspace/files/:name read (Agent read) or replace (Agent operate) one file in the live workspace. See live file access.

Native admin UI

Authorized users can open the selected Agent gateway's native browser UI when the Installation enables Agent native admin UI access. The availability route requires exact Agent operate for chat or administer for administration. read alone is insufficient. The Agent must be desired running, have a selected version, and expose a private gateway endpoint through the selected Compute Driver.

A derived per-Agent browser host proxies to the private gateway route using the OCE session cookie under the shared cookie parent domain; OCC still authorizes the exact Agent (session boundary). Native edits do not become Configuration changes or AgentRevision snapshots, and redeploy does not erase all gateway-local state (drift).

Namespace ownership

An Agent belongs to the Namespace in its creation URL; request bodies cannot select a different Namespace or Installation. Names are unique within each Namespace, and cross-Namespace access requires separate scoped permissions. A failed or deleting Namespace rejects new Agents.

Identity and deployment

Each Agent has one stable service principal and runs embedded OpenClaw or dedicated Codex. A deployment request takes no body: it snapshots the saved draft, and a worker starts it asynchronously. See Agent identity and deployment for permissions, snapshot fields, and activation guarantees.

An authorized bodyless POST /namespaces/:namespaceId/agents/:agentId/stop sets desired state to stopped. The worker removes execution and routing, then clears activeRevisionId; version history, credentials, and persistent state remain. Cleanup includes failed candidate resources and interrupted predecessor retirement owned by the current Compute. Repeating stop is safe. To resume, deploy a new version; old versions cannot be restarted. See stop and resume.

Deletion

A bodyless DELETE /namespaces/:namespaceId/agents/:agentId requires exact-Agent delete, sets status: deleting and desired state stopped, queues teardown, and returns 202. Reads remain available; updates, deployment, credential provisioning, and workspace writes return 409. Repeated DELETE leaves queued or running work unchanged.

The worker reauthorizes the caller, binds the saved identity to Compute, retires every version, and removes runtime credentials. It atomically deletes the Agent, its Agent revisions, service principal, API keys, and exact IAM bindings and restrictions. Kubernetes retirement waits for owned Pods and removes owned artifacts, including workspace data. Namespace Configurations and Secrets survive. Deletion releases its name; repository cleanup continues independently.

Permanent failure or exhausted attempts leave the Agent deleting. After a fix, the initiating caller can repeat DELETE to reset attempts; OCC and the worker recheck permission. Another permitted actor gets 403, audited with the initiatingActorId, until the initiator loses permission, then takes over. Prior failure audits remain and each retry is audited, as in Namespace recovery.

Editable configuration

An Agent's configurationId selects exactly one native OpenClaw Configuration document with kind: "agent" in its own Namespace. A PATCH requires configurationId, exact-Agent update, and exact-Configuration read. This replaces the reference, preserving execution mode, harness binding, and Backend:

json
{  "configurationId": "cfg_123e4567-e89b-42d3-a456-426614174000"}

Edit the Configuration's native document through its own exact-resource PATCH endpoint (Configuration CRUD). Changing the Agent reference or Configuration values does not queue Compute work, change the selected version, or mutate earlier versions. Create/update reject inline configuration and competing gateway settings. Agents can share a Configuration; deployed Agents keep separate gateways and stable service principals.

Current limitations

The public API has no Agent revision mutation/deletion or explicit rollback endpoint. Controller API authentication for Agent service principals remains unavailable. The OpenShell SandboxDriver requires Kubernetes Compute with dedicated Codex or worker-capable native OpenClaw. Its Credential Gateway mediates model sources; direct Secret delivery remains unsupported. Check its compatibility limits.

Failure semantics

Search documentation