Agent harness runtime configuration

Operator configuration: turning on the bundled native Codex mode, and pinning provider, model, or per-agent runtime policy so a missing harness fails instead of routing through the embedded runtime. Part of the Agent harness plugins reference.

Native Codex harness mode

The bundled codex harness is the native Codex mode for embedded OpenClaw agent turns. Enable the bundled codex plugin first, and include codex in plugins.allow if your config uses a restrictive allowlist. Native app-server configs should use openai/gpt-*; OpenAI agent turns select the Codex harness only when the effective route declares Codex compatibility. Legacy Codex model refs should be repaired with openclaw doctor --fix, and legacy codex/* model refs remain compatibility aliases for the native harness.

When this mode runs, Codex owns the native thread id, resume behavior, compaction, and app-server execution. OpenClaw still owns the chat channel, visible transcript mirror, tool policy, approvals, media delivery, and session selection. Use provider/model agentRuntime.id: "codex" to require a registered Codex harness. Unsupported routes/auth fail closed unless the harness declares an exact-request fallback before execution. Codex runtime failures are not retried through another runtime.

Agents API environment

The agentsapi plugin accepts plugins.entries.agentsapi.config.environment with the values openai_hosted and self_hosted. Omitted configuration uses openai_hosted.

For self_hosted, OpenClaw sends its prepared absolute workspace path as the Agents API workspace_directory. The executor must already have that directory at the same path. Before selecting this mode, configure an operator-owned webhook controller for the Gateway's sessions. The controller retrieves each session's environment ID and remote URL through the authenticated Agents API and connects its executor, following the official self-hosted setup. It owns startup, reconnection, and cleanup. OpenClaw does not launch or provision executors through this setting. Input submission has a 60-second HTTP deadline, including any wait for the executor to connect. The controller must connect promptly; the API's longer connection window does not extend this deadline.

Set plugins.entries.agentsapi.config.hostExecutorSkillDirectories to absolute paths on the executor host machine. These directories must already be set up with the skill files and be available to the Agents API harness through the executor. OpenClaw sends the paths as the Agents API capability_directories field. The harness discovers and reads skills through that executor; OpenClaw does not copy or install the files. This explicit directory selection uses native skill discovery, without OpenClaw's per-skill eligibility filters. Gateway function policies still apply. Omitted and empty lists keep the existing behavior. Hosted sessions ignore this list.

Reset the OpenClaw session after changing its environment or a self-hosted workspace or skill directories. Existing hosted sessions continue with omitted or explicit openai_hosted configuration. This selection does not expand the MVP's existing tool or media capabilities.

Agents API HTTP MCP servers

The Agents API harness reads enabled HTTP servers from mcp.servers and plugin MCP bundles. Set transport: "streamable-http", a url, and optional headers on each server. HTTP connections run from the session's execution environment, including the self-hosted executor for private-network services. Native MCP owns discovery and execution; OpenClaw does not create another Gateway transport for these tools.

Exact toolFilter.include names are forwarded as the native allowlist. Exclusions and session tool denials require an explicit include list and are subtracted from it. Wildcards, Gateway-managed OAuth, legacy SSE and custom TLS settings are not supported. Unsupported servers and servers whose headers cannot be resolved are omitted with an error log, while supported servers remain available. This includes requester-scoped connections and URL-only definitions, which retain the legacy SSE default. Changes to effective MCP configuration or credentials require a session reset.

Stdio MCP forwarding remains a deferred implementation gap. The executor's native MCP lifecycle will own those processes when support is added.

Harness authors can reuse loadAgentHarnessMcpConfig from openclaw/plugin-sdk/agent-harness-runtime to merge enabled bundle and operator definitions with session server overrides. It returns static connection config, diagnostics, and the names of omitted requester-scoped servers, without opening connections. The same SDK exports decodeHeaderEnvPlaceholder for recognizing ${NAME} and Bearer ${NAME} header references; the harness resolves the value for its own transport. Read the returned server's transport field. Doctor normalizes operator config, and bundle loading translates external type fields before this boundary. Transport support and the default for servers without transport remain the harness's responsibility.

Runtime strictness

By default, OpenClaw uses auto provider/model runtime policy: registered plugin harnesses can claim compatible effective routes, and the embedded runtime handles the turn when none match. A provider/model prefix alone never selects a harness. Use an explicit provider/model plugin runtime such as agentRuntime.id: "codex" when missing harness selection should fail instead of routing through the embedded runtime. Explicit selection does not make an incompatible route compatible. Selected plugin harness failures always fail hard. This does not block an explicit provider/model agentRuntime.id: "openclaw".

To request Codex for embedded runs:

{
  "models": {
    "providers": {
      "openai": {
        "agentRuntime": {
          "id": "codex"
        }
      }
    }
  },
  "agents": {
    "defaults": {
      "model": "openai/gpt-6-astra"
    }
  }
}

If you want a CLI backend for one canonical model, put the runtime on that model entry:

{
  "agents": {
    "defaults": {
      "model": "anthropic/claude-opus-5",
      "models": {
        "anthropic/claude-opus-5": {
          "agentRuntime": {
            "id": "claude-cli"
          }
        }
      }
    }
  }
}

Per-agent overrides use the same model-scoped shape:

{
  "agents": {
    "entries": {
      "codex-only": {
        "model": "openai/gpt-6-astra",
        "models": {
          "openai/gpt-6-astra": {
            "agentRuntime": { "id": "codex" }
          }
        }
      }
    }
  }
}

Legacy whole-agent runtime examples like this are ignored:

{
  "agents": {
    "defaults": {
      "agentRuntime": {
        "id": "codex"
      }
    }
  }
}

With an explicit plugin runtime, a session fails early when the requested harness is not registered or rejects the resolved provider/model without a declared fallback. An authored transport override may select OpenClaw through that fallback even with an explicit runtime. To prove native execution, inspect the actual harness in the completed result; configured intent alone is not proof.

This setting only controls the embedded agent harness. It does not disable image, video, music, TTS, PDF, or other provider-specific model routing.