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

<a id="agents-api-mvp" />
<a id="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.

<a id="what-works-with-a-hosted-vm" />

### 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](/plugins/agentsapi#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:

```bash
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](/providers/openai/setup#getting-started) 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.

```json5
{
  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](/plugins/sdk-agent-harness/runtime-config)
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](/concepts/models#choose-the-same-model-with-different-runtimes).
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](/plugins/agentsapi#work-with-files-and-tools).

<a id="sessions-and-instructions" />

## Continue a task

Follow-up messages use the same Agents API session. When switching an existing
OpenClaw conversation to Agents API, the new native session receives bounded,
quoted prior conversation context, including recorded tool outcomes. Returning
to a retained Agents API session also supplies work recorded outside that native
session since its last completed reply. This context does not replay tools or
copy local files into the hosted workspace. If an older checkpoint is outside
the bounded history window, some quoted reference context may repeat.

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](https://github.com/openclaw/openclaw/blob/main/extensions/agentsapi/README.md#upgrading-saved-sessions)
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.

<a id="tools-mcp-and-files" />
<a id="tools%2C-mcp%2C-and-files" />

## 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](/plugins/agentsapi#forwarding-controls) separately
without disabling hosted commands, files, or attachments. You can also connect
remote tools through MCP; see
[MCP connections](/plugins/agentsapi#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](https://developers.openai.com/api/docs/guides/agents-api/environments/openai-hosted)
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:

```json5
{
  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](https://github.com/openclaw/openclaw/blob/main/extensions/agentsapi/README.md)
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:

```text
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](https://developers.openai.com/api/docs/guides/agents-api/environments/self-hosted)
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](https://developers.openai.com/api/docs/guides/agents-api/environments/lifecycle#start-compute-from-webhooks).
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`:

```bash
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:

```json5
{
  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](https://github.com/openclaw/openclaw/blob/main/extensions/agentsapi/README.md)
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.

<a id="current-limits-and-other-environments" />

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