openclaw/docs/plugins/agentsapi.md

summary	doc-schema-version	read_when	title
Use the cloud-hosted Agents API harness, powered by Codex, with OpenClaw	1	You want to set up Agents API as your OpenClaw agent runtime You want hosted execution with your chat channels, instructions, and tools	Agents API

What is Agents API?

The bundled agentsapi plugin replaces OpenClaw's built-in agent harness with the Agents API harness, which uses the Codex harness under the hood. The agent harness runs in OpenAI's cloud. It manages the conversation and the loop of calling the model, using tools, and continuing a task.

OpenClaw connects that harness to your chat channels, personal instructions, memory, and configured tools. You keep interacting with your assistant through the same channels, with progress, replies, and generated files delivered back to the conversation.

With the hosted setup in this guide, OpenAI also provides the Linux environment where your agent runs code and works with files. You can ask it to analyze data, research a topic, or generate a file, then refine the result through follow-up messages without provisioning a separate execution machine.

What you can do

• Run code and analyze data. Ask the agent to use Python, Node.js, or shell commands to calculate results, process a dataset, or automate a task.
• Work with files in chat. Send a document or data file, ask the agent to transform it, and download the finished output from its reply.
• Research and use connected tools. Combine built-in web search with your enabled OpenClaw tools, memory, and connected MCP servers.
• Keep working through follow-ups. Refine a result, add another file, or redirect work while it is running, all in the same conversation.
• Keep your assistant's context. New sessions receive your OpenClaw persona and instructions, so the agent can work with your preferences from the start.

The hosted setup is intended for a personal, single-user Gateway. If you want commands to run on infrastructure you manage, see self-hosted execution.

Set up Agents API

Start with a working OpenClaw Gateway and a chat channel. You will also need an OpenAI API key and a model available to your Agents API project.

1. Sign in with an API key

Run:

openclaw models auth login --provider openai --method api-key

Use a key with Agents and Responses read/write plus Models read permission. The runtime uses the official https://api.openai.com/v1 endpoint with the openai-responses adapter. See OpenAI setup for authentication help.

Requests identify OpenClaw with User-Agent: openclaw/<version>, originator: openclaw, and version: <version>, using the same attribution headers as other native OpenAI requests.

2. Enable the plugin and choose your model

Merge this into your existing openclaw.json, keeping your channel settings and other plugins. Replace YOUR_MODEL_ID in both places with a model available to your Agents API project.

{
  plugins: {
    entries: {
      agentsapi: { enabled: true },
    },
  },
  agents: {
    defaults: {
      model: { primary: "openai/YOUR_MODEL_ID" },
      models: {
        "openai/YOUR_MODEL_ID": { agentRuntime: { id: "agentsapi" } },
      },
    },
  },
}

If you use plugins.allow, add agentsapi and openai to that list. Enabling the plugin makes it available; the model's agentRuntime setting selects it for conversations. See runtime configuration for provider and per-agent model settings.

Shared model tuning

Agents API uses its own native context management. Shared OpenClaw settings responsesServerCompaction and responsesCompactThreshold do not prevent selecting it, but they do not control hosted compaction (including when responsesServerCompaction is false). They keep their existing behavior when you use the same model with the OpenClaw runtime. Model capability metadata such as supportsTemperature and codeMode also does not require an exact native implementation.

This is best-effort tuning compatibility, not permission to drop request policy. Custom endpoints, authentication, headers, request parameters, and storage behavior still require a runtime that can honor them; Agents API continues to require its official API-key route.

3. Start a conversation and try a task

In the Control UI, open New session → Environments and select OpenAI (Agents API) under Hosted workspaces. The option uses the Gateway’s configured model/runtime choices and API-key availability. If another runtime should remain your default, add pickerRuntimes: ["agentsapi"] to the exact model entry instead of changing its agentRuntime. See model runtime choices. The hosted choice does not copy your selected local folder, project, or worktree; send input files as chat attachments. Switching back restores your local draft choices and requires an available compatible host runtime.

Apply the configuration through your usual Gateway workflow. In your chat channel, send /new, then try:

Use Python to calculate the sum of the squares from 1 to 100 and show me the result.

Look for the calculation result, 338350. This checks the path from your chat to hosted code execution and back. Then ask the agent to repeat the calculation for 1 to 200 to try a follow-up in the same session. You can explore attachments and generated files in Work with files and tools.

Continue a task

Follow-up messages use the same Agents API session. Ask the agent to revise its answer, work with another attachment, or take the next step. A message sent while the agent is working can redirect it; stopping the task cancels its remote turn.

Saved sessions from v2026.9.9 are upgraded on their first continuation without changing the remote session ID. Keep the original API key and configuration until that continuation succeeds. If they no longer match, the plugin retains the binding and explains how to restore them or explicitly reset with a key that can settle the original native session. A failed upgrade never silently creates a replacement conversation. See the saved-session upgrade notes for key rotation and rollback.

New sessions receive your OpenClaw instructions and persona, including AGENTS.md, SOUL.md, and your user context. After editing those instructions, send /new or /reset to start a conversation with the updated context. Your enabled memory tools can also search and recall information through the Gateway.

Work with files and tools

Attach a file to a message and describe the result you want. For example:

Summarize this CSV by month and send me a new CSV containing the totals.

Attachments arrive in the agent's hosted workspace. To receive a generated file, ask the agent to save it under /workspace/outputs and return it in the reply. Download outputs you want to keep: the hosted workspace is separate from your Gateway's files, and a saved conversation does not guarantee permanent file storage.

Built-in web search is available in new sessions unless disabled globally with tools.web.search.enabled: false or through the session’s Web search control. Changing the effective search setting requires /new or /reset; an existing session refuses to continue with a different native search policy. By default, your enabled OpenClaw and plugin tools remain available under your configured tool policies, including memory search and recall. You can disable Gateway tool and MCP forwarding separately without disabling hosted commands, files, or attachments. You can also connect remote tools through MCP; see MCP connections below.

Advanced configuration and reference

The sections below cover storage, tool connections, self-hosted execution, and current limitations. The setup above is enough to start using the hosted environment.

Files and storage

Incoming files are placed in /workspace/inputs. Files returned with a completed reply come from /workspace/outputs. Transfers support up to 5 MiB per file, 10 MiB total, and 50 files per turn in each direction.

Your Gateway workspace and the hosted filesystem serve different purposes. Instructions are supplied as context; send files as attachments when the agent needs their contents in its workspace. See the hosted environment guide for environment lifecycle and storage behavior.

Forwarding controls

To use the hosted environment without exposing Gateway function callbacks or configured MCP servers, merge this into your existing configuration:

{
  plugins: {
    entries: {
      agentsapi: {
        enabled: true,
        config: {
          forwarding: {
            gatewayTools: false,
            mcpServers: false,
          },
        },
      },
    },
  },
}

Both settings default to true and are independent:

• gatewayTools: false skips constructing OpenClaw and plugin tools for Gateway function callbacks. No Gateway functions are declared, and unexpected remote function calls are rejected without invoking a tool or its execution hooks.
• mcpServers: false skips loading configured and plugin-bundled MCP servers, including discovery and credential resolution. It also excludes servers added later; it is not a list of currently known server names.

Set both to false for no forwarded Gateway functions or MCP servers. A native shell/file tool allowlist alone does not disable MCP forwarding. These controls apply only to the Agents API plugin, not other harnesses or the Gateway's own tool configuration. Native hosted shell and file operations, attachment uploads, output artifact delivery, and same-session follow-ups remain available.

Native tool declarations are separate. To omit hosted web search, set plugins.entries.agentsapi.config.nativeTools to a list without web_search, for example [{ type: "programmatic_tool_calling", enabled: true }]. A supplied list replaces the defaults. These forwarding controls do not change native shell, file, or web-search permissions or bypass the existing preflight checks.

Apply the configuration through your usual Gateway workflow, then use /new or /reset. Remote tool declarations are fixed for a session: changing either forwarding setting refuses continuation and retains the original binding until you reset it. Reset and deletion can still settle the saved native session under the new policy; the plugin never silently creates a replacement conversation.

This is tool-exposure isolation, not full Gateway prompt or persona isolation. OpenClaw instructions, persona, and ordinary prompt/lifecycle hooks still apply. Tool-authorized prompt hooks receive only the exposed Gateway function names, which are empty when Gateway tool forwarding is disabled.

MCP connections

Configure remote MCP servers in mcp.servers or an enabled plugin's MCP bundle with the streamable-http transport. The hosted environment must be able to reach the server's URL. Supply HTTP authentication headers when required; localhost refers to the hosted environment.

Start a new conversation with /new or /reset after changing MCP configuration or credentials. The plugin reference has connection settings, header references, and tool filters.

Self-hosted execution

Self-hosted execution keeps the agent harness in OpenAI's cloud and runs commands and file operations on infrastructure you manage. The bundled agentsapi plugin owns the conversation and native session. An external lifecycle owner connects that session to a codex exec-server process on your host and manages its cleanup.

One executor per session

Each native Agents API session has its own environment ID, connection URL, and executor process. Follow-up turns reuse that session and executor. Starting another conversation creates another session with its own executor.

All executors can run in the same persistent environment, such as one VM, remote host, or container, and use the same workspace directory. This is one possible deployment, not a requirement. You can instead place executors in separate environments according to your isolation and persistence needs.

For example, two conversations can have this layout:

OpenClaw Gateway                 One persistent remote host
  Conversation A -> Session A -> Executor A --+--> /srv/agent/workspace
  Conversation B -> Session B -> Executor B --+

The sessions have separate conversation histories and executor connections, but share the files and installed software on that host. Session separation is not filesystem or credential isolation. Concurrent sessions can change the same files; use separate workspaces, users, or hosts when workloads need isolation. Retiring one session's executor must leave other executors and the shared workspace intact. Your host's storage and backup policy determine file durability.

1. Prepare the execution host

Complete the API-key and model setup above. On the execution host, prepare an absolute workspace path, install the tools and dependencies your agent needs, and install a Codex CLI version supporting codex exec-server. Follow the official self-hosted setup for the current installation and outbound-network requirements.

Provision a restricted environment key from the platform dashboard for the same organization, project, and user or service account as the session owner. Supply that key to the executor as CODEX_API_KEY; keep the Gateway's application API key out of the executor environment. Your external lifecycle owner is responsible for secure credential delivery, host access, process supervision, and filesystem provisioning.

2. Configure external executor management

Use an external lifecycle owner, for example through the Agents API webhook lifecycle. It owns session-scoped startup, reconnection, and cleanup. It must authenticate API reads, handle only its intended sessions, and use each session's environment ID and unchanged remote URL. The workspace path sent by OpenClaw must already exist at the same absolute path on the executor. Choose one lifecycle owner for each session.

An external owner typically launches this command on the execution host, in its prepared workspace, with the environment key supplied securely as CODEX_API_KEY:

codex exec-server \
  --remote "<session.environment.remote_url>" \
  --environment-id "<session.environment.id>"

Use a separate managed process for each native session and make startup safe to repeat. Reconnection does not guarantee an interrupted command survives. Check the original turn's outcome before repeating work that may have changed files or called a service. Input submission has a 60-second HTTP deadline, including connection wait, so prepare hosts to connect promptly.

3. Select self-hosted execution

Merge this into your existing configuration and keep your model's agentRuntime.id: "agentsapi" setting from the setup above:

{
  plugins: {
    entries: {
      agentsapi: {
        enabled: true,
        config: { environment: "self_hosted" },
      },
    },
  },
}

Optionally set plugins.entries.agentsapi.config.hostExecutorSkillDirectories to absolute skill-directory paths on the execution host. Provision their files and dependencies yourself. OpenClaw forwards the paths for native discovery; it does not copy Gateway skills to the host.

Apply the configuration and start a fresh conversation with /new or /reset. Changing the environment or workspace for an existing conversation requires a reset. It does not migrate files between hosts. OpenClaw settles native work before reset or deletion removes the local session binding; your external owner remains responsible for stopping the session's executor.

Upgrading from a controller plugin

executorController and api.registerAgentExecutorController are no longer supported. Before upgrading, use the previous OpenClaw version with the original controller plugin to retire every controlled session and verify its executor has stopped. Then remove executorController and configure an external lifecycle owner before starting new self-hosted sessions. This is a deployment migration, not an automatic transfer of executor ownership.

The new version rejects the old configuration and retains any saved controller binding, including records written before executor startup completed. Run, reset, deletion, and transcript context reset cannot discard these records. Return to the previous version and original controller to complete cleanup; removing the configuration key alone does not migrate an existing controlled session.

Check the setup and file boundaries

Start with the calculation from the hosted setup, then ask the agent to write a small file in its workspace and read it in a follow-up. For a shared-host setup, start a second conversation and check that it uses a different executor while seeing the same file. Reset one conversation and confirm the other still works and the shared file remains. Inspect controller process records and Gateway logs as well as the chat reply; a model-authentication probe does not test an executor connection.

Executor management does not automatically synchronize Gateway files or add attachment transfer. Self-hosted input attachments require a registered workspace provider with attachment staging. External executor management does not add automatic self-hosted output transfer. Configure the appropriate workspace/file integration for your deployment, or use the hosted environment for its built-in transfers. Gateway memory and tools retain their own storage and permissions. See the package reference for these boundaries and upgrade notes.

Session settings and diagnostics

Use /new or /reset to adopt changes to session instructions, MCP connections, forwarding controls, or reasoning-summary display. These commands start a fresh session on the next message. Remote history and workspace resources remain managed through the Agents API.

Reset and deletion confirm that native work has stopped before removing a session binding, including after a Gateway restart. If that confirmation fails, the binding is retained for recovery. This does not delete the remote conversation or its retained files. Rewinding or switching a local transcript branch also invalidates its old native binding after the local change commits. External executor cleanup remains the responsibility of its lifecycle owner.

OpenClaw shows progress and records conversation and tool history in its normal transcript. Channel settings control progress and reasoning visibility. Token usage is reported when available from the API; it measures usage rather than remaining context capacity.

For an end-to-end setup check, use the Python calculation above. openclaw models status --probe checks model authentication, not a complete Agents API session.

Current limitations

These limits describe the current OpenClaw integration and may change as support expands.

• Authentication: ChatGPT subscription authentication, custom endpoints, and authored request transport overrides are not supported by the Agents API runtime. Use the API-key setup above.
• Hosted environment setup: The plugin does not expose hosted skill installation or operator-configured startup commands, packages, environment variables, or environment templates. Gateway scripts, repositories, and skill directories are not automatically copied into the hosted environment. A self-hosted executor must be provisioned by its operator.
• Instructions and skills: Changes to workspace instructions or persona need a new session. Gateway skill-file access, skill catalog delivery, and plugin command prompt registration are not yet supported by this runtime.
• Agent features: Native delegation, including ultra delegation, and native session forks are not supported. Native Codex project discovery, collaboration, and deferred tool search do not apply to this runtime.
• Images and runtime customization: Image input, image generation, Gateway sandbox placement, and custom context engines are not supported.
• MCP connections: Stdio, legacy SSE, requester-scoped connections, and custom TLS settings are not supported. Gateway OAuth profiles are not forwarded. Unsupported definitions are logged and omitted, and a turn can continue without an unavailable server.
• Tool restrictions and hooks: Policies that restrict native shell, file, or web-search capabilities are rejected before a turn starts. Hook toolsAllow restrictions are not enforced; use another runtime if you depend on those per-turn restrictions. Gateway tool policies still apply. Steering and isolated completions do not run conversation prompt hooks.
• History and diagnostics: Structured plans, diffs, compaction events, native child-agent events, and pre-execution approval or hook events are not provided. History can be incomplete or out of order while tool results are still arriving. Web-search activity is visible without result bodies or snippets. Command exit facts can be unavailable, and token usage does not establish remaining context capacity.
• Retries: OpenClaw can continue the existing session after a transient provider failure. It does not automatically replay an admitted turn because commands or tools may already have run.