How to run OpenClaw on the Agents API harness

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 through the same channels, with progress, replies, and generated files delivered back to the conversation. With this hosted setup, OpenAI also provides the Linux environment where the 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.

The hosted setup is intended for a personal, single-user Gateway. If you want commands to run on infrastructure you manage, the same plugin page documents a self-hosted executor instead. The steps below stay on the hosted path. That setup is enough to start using the hosted environment.

What you need

Start with a working OpenClaw Gateway and a chat channel. You also need an OpenAI API key and a model available to your Agents API project. A specific model id is not prescribed.

The runtime uses the official https://api.openai.com/v1 endpoint with the openai-responses adapter. Requests identify OpenClaw with User-Agent: openclaw/<version>, originator: openclaw, and version: <version>, using the same attribution headers as other native OpenAI requests.

Run:

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

Use a key with Agents and Responses read/write plus Models read permission. ChatGPT subscription authentication, custom endpoints, and authored request transport overrides are not supported by the Agents API runtime. Use the API-key setup above.

openclaw models status --probe checks model authentication, not a complete Agents API session.

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. Apply the configuration through your usual Gateway workflow.

Start a conversation and try a task

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. An expected result for that second range is not published.

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.

The agent can use Python, Node.js, or shell commands to calculate results, process a dataset, or automate a task. New sessions receive your OpenClaw persona and instructions, including AGENTS.md, SOUL.md, and your user context. After editing those instructions, send /new or /reset. Use the same commands after changing MCP configuration, credentials, or reasoning-summary display. They start a fresh session on the next message. Remote history and workspace resources remain managed through the Agents API.

Enabled memory tools can search and recall information through the Gateway. Built-in web search is available in new sessions. Enabled OpenClaw and plugin tools remain available under your configured tool policies, including memory search and recall. 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.

Work with files

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. Incoming files are placed in /workspace/inputs. Files returned with a completed reply come from /workspace/outputs. 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.

Transfers support up to 5 MiB per file, 10 MiB total, and 50 files per turn in each direction. Instructions are supplied as context. Send files as attachments when the agent needs their contents in its workspace. Gateway scripts, repositories, and skill directories are not automatically copied into the hosted environment.

MCP connections and current limits

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. In this setup, localhost refers to the hosted environment. Start a new conversation with /new or /reset after changing MCP configuration or credentials.

These limits describe the current OpenClaw integration and may change as support expands. ChatGPT subscription authentication, custom endpoints, and authored request transport overrides are not supported. Image input, image generation, Gateway sandbox placement, and custom context engines are not supported. 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.

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. The plugin does not expose hosted skill installation or operator-configured startup commands, packages, environment variables, or environment templates. A self-hosted executor must be provisioned by its operator. hostExecutorSkillDirectories can expose skill directories installed on that executor.

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

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

What to try next

Send /new in a chat channel after the API-key login, with the plugin enabled and the model agentRuntime id set to agentsapi. Run the sum-of-squares prompt and confirm 338350. Then ask for the same calculation from 1 to 200 in that session, or attach a small file and ask for a result saved under /workspace/outputs. Before relying on ChatGPT subscription auth, custom endpoints, image input, stdio MCP, or native delegation, read the current limitations. Those paths are unsupported in this integration.

Sources

Agents API plugin