agents.md

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.

Deploy your first 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:

{
  "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

For unreadable saved settings, Agent and Agent revision list/detail GETs omit them without defaults, keep readable metadata and siblings, and add configurationReadError with code: "SAVED_CONFIGURATION_UNREADABLE" and the affected field. 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:

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.

• queued: no live claim; PostgreSQL's clock judges lease expiry.
• running: a live worker claim.
• succeeded: original work activated the version or found it already selected.
• failed: terminal failure or completion without activation.

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 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. 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:

{
  "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

Initial contents at creation

POST /namespaces/:namespaceId/agents accepts initialWorkspaceFiles, an optional partial map of the four filenames below to strings. Replace the example Configuration ID:

{
  "name": "Support assistant",
  "configurationId": "cfg_12345678-1234-4123-8123-123456789abc",
  "initialWorkspaceFiles": {
    "AGENTS.md": "Answer support questions.\n",
    "USER.md": ""
  }
}

Omission or {} uses native initialization; omitted filenames keep native behavior. Empty strings create empty files. Values must satisfy the live-file Unicode and 16 KiB limits below; other names and non-strings are rejected. The API preserves whitespace and newlines. Create requests default to 448 KiB, including JSON escaping; configured controller limits take precedence.

Creation uses existing permissions and stages inputs privately outside Agent, Configuration, and AgentRevision. First deployment applies them before execution. Completion prevents replay over later edits. Staged bytes are removed after activation or Agent deletion. Pending inputs have no read/update API; correction requires deleting and recreating the Agent.

The optional workspaceDefaultsId is a SHA-256 defaults identity. Console sends all four rendered 2026.9.9 defaults with this identity. A stale identity rejects creation with 409 RESOURCE_CONFLICT; runtime mismatch blocks initial setup. See the workspace guide and setup flow for recovery and runtime requirements.

Live file access

Read, create, or replace AGENTS.md, SOUL.md, IDENTITY.md, and USER.md in an Agent's live workspace:

/namespaces/:namespaceId/agents/:agentId/workspace/files/:name

Method	Operation	Agent permission	Response data
GET	Read the file	read	{ name, content }
PUT	Create or replace the file	operate	{ name, size }

Authenticate with a session or scoped service API key. Session-authenticated writes must pass the CSRF checks. The Agent must have an selected version and a reachable gateway.

Embedded OpenClaw sole rosters follow the Gateway-announced default ID. Other rosters retain the explicit main target; dedicated deployment requires it.

PUT accepts one content field:

{ "content": "You are a support assistant.\n" }

content must be well-formed Unicode without NUL characters and fit within 16 KiB when encoded as UTF-8. The complete request body is limited to 97 KiB, enough for 16 KiB written entirely in six-byte JSON escapes. Success returns 200. A successful PUT reports size in UTF-8 bytes and records the Agent, file name, and outcome in the audit log.

Error	Meaning
400 INVALID_REQUEST	Invalid file name or content.
404 NOT_FOUND	The requested Agent or file was not found.
409 AGENT_DELETING	The Agent is being deleted.
409 RESOURCE_CONFLICT	The Agent is stopping.
413 PAYLOAD_TOO_LARGE	The request body exceeds 97 KiB.
503 DEPENDENCY_UNAVAILABLE	Workspace access is unavailable.
503 UNKNOWN_OUTCOME	OCC could not confirm the write or its audit record.

After UNKNOWN_OUTCOME, read the current file before deciding whether to submit another write.

See gateway routing for transport, workspace-file setup to enable access, the HTTP API for schemas, and the execution flow for implementation.

Native admin UI

Trusted operators can open the selected Agent gateway's stock native admin UI when the Installation enables Agent native admin UI access. The availability route requires exact Agent administer; read and operate are 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:

{
  "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

• 400 INVALID_REQUEST: The Backend ID is malformed or empty, the plugin map is structurally invalid, or a runtime modelApiKey selector is supplied (use harnessAuth).
• 404 NOT_FOUND: The nonempty Backend ID does not name a configured Backend.
• 401: The session cookie is missing, invalid, expired, or revoked.
• 403: Your principal lacks the exact permission for the Agent or Namespace.
• 404: The Namespace or Agent does not exist under the requested parent, or the selected Configuration or associated service account is not in the Agent's Namespace.
• 409 RESOURCE_CONFLICT: Harness authentication is missing, the selected account has no issued access token, or its Backend binding or topology is incompatible.
• 409 SERVICE_ACCOUNT_DRIVER_NOT_CONFIGURED: The account has no access token, and the Installation has no ChatGPT Backend to issue one.
• 409 RESOURCE_CONFLICT: Another Agent already uses that name in the same Namespace, the Namespace cannot accept new Agents, or a stopping Agent cannot accept the requested mutation.
• 409 AGENT_DELETING: The Agent is deleting and rejects the mutation.
• 409 NAMESPACE_NOT_READY: The backing Namespace infrastructure is not ready for deployment.
• 503 DEPENDENCY_UNAVAILABLE: A selected Harness descriptor, Compute implementation, or other required dependency is unavailable.
• 503 RUNTIME_CREDENTIALS_CLUSTER_RBAC: The cluster denied the API ServiceAccount access to the Agent's runtime credential Secrets or Deployment preflight. An operator must grant the tenant RoleBindings.

Related

• Deploy your first Agent
• Agent Revisions
• Workspace files
• Troubleshoot Agents
• Development and production deployment
• Harness execution
• Namespaces
• Controller worker
• Namespace Configuration and immutable snapshots
• Service accounts
• Agent plugins
• Kubernetes Compute Driver
• IAM
• Controller configuration
• Platform architecture
• Agent lifecycle implementation
• HTTP resource schemas
• Local testing

Manual Notes

[keep this for the user to add notes. do not change between edits]

Changelog

• 2026-09-23: Removed top-level Agent.serviceAccountId checks; use harnessAuth. (NOT_IN_SPEC)

• 2026-09-01 08:47: Document nullable providerId selection, immutable version association, and managed binding admission. (01a05d97-f2b0-71d0-bfc3-01ee7d6d58f9 - b079c4b755ef336a9c65bb4eb737e3aedbfdaa7d)

• [2026-08-28 17:55]: Recast as the current Agent and AgentRevision feature reference; separate procedures and correct Harness and SandboxDriver boundaries. (01a036f4-cf1d-7cc1-bbc1-000879038ac8 - 4270aa29b7015562049f46c6027962fd85b584a9)