OpenAI Agents API (hosted harness)

v2026.9.7 shipped the bundled agentsapi plugin. It replaces OpenClaw's built-in agent harness with OpenAI's Agents API (Codex harness under the hood). The loop of model → tools → continue runs in OpenAI's cloud. You still talk through the same channels; progress, replies, and generated files come back to the conversation. Official: docs.openclaw.ai/plugins/agentsapi.

This is not Sign in with ChatGPT. ChatGPT subscription auth, custom endpoints, and authored request-transport overrides are not supported. Use a Platform API key with Agents and Responses read/write plus Models read. Hosted setup is documented as a personal, single-user Gateway. For machines you provision yourself, see cloud workers or the plugin's self-hosted executor path.

Enable it

Working Gateway + a chat channel + an API key. Then:

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

Merge into existing openclaw.json (keep channels). Replace YOUR_MODEL_ID with a model your Agents API project actually has:

{
  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. Enabling the plugin only makes it available; agentRuntime selects it for conversations. In Control UI: New session → Environments → OpenAI (Agents API) under Hosted workspaces. That choice does not copy a local folder or worktree—send files as chat attachments.

Keep another runtime as default by adding pickerRuntimes: ["agentsapi"] on that model entry instead of changing agentRuntime.

Smoke test

In the channel, /new, then ask it to use Python to sum the squares from 1 to 100. Official check value: 338350. That proves chat → hosted code → reply. Follow up in the same session (1 to 200) to confirm continuation. openclaw models status --probe only checks model authentication, not a full Agents API session.

Files and forwarding

  • Inbound files land in /workspace/inputs. Ask the agent to write keepers under /workspace/outputs. Transfers: 5 MiB per file, 10 MiB total, 50 files per turn, each direction.
  • The hosted filesystem is not your Gateway workspace. A saved conversation does not guarantee permanent remote files. Download what you need.
  • New sessions get OpenClaw persona/instructions (AGENTS.md, SOUL.md, user context). After you edit those, /new or /reset.
  • Default: enabled OpenClaw tools and MCP can be forwarded. To keep hosted shell/files but skip Gateway function callbacks and MCP:
plugins.entries.agentsapi.config.forwarding: {
  gatewayTools: false,
  mcpServers: false
}

Both default to true and are independent. Changing forwarding on an existing conversation refuses continuation until you /new or /reset. That is tool-exposure isolation, not full persona isolation.

What this runtime does not do (current)

  • No hosted skill install, startup templates, or automatic copy of Gateway skill directories.
  • No native delegation (ultra), session forks, image input/generation, Gateway sandbox placement, or custom context engines.
  • MCP: streamable-http only. Stdio, legacy SSE, requester-scoped connections, custom TLS, and Gateway OAuth profiles are omitted.
  • Saved sessions from v2026.9.9 upgrade on first continuation without changing the remote session ID. Keep the original API key until that succeeds. A failed upgrade never silently creates a replacement conversation.

Self-hosted execution keeps the harness in OpenAI's cloud and runs commands on a host you manage via codex exec-server and an external lifecycle owner. executorController is no longer supported—retire old controlled sessions on the previous version before you upgrade. Details stay on the official plugin page.

Related