<!-- source: https://deepwiki.com/openclaw/openclaw/3.9-codex-and-cli-backends -->

# Codex & CLI Backends

- CHANGELOG.md
- docs/gateway/cli-backends.md
- docs/plugins/codex-harness-reference.md
- docs/plugins/codex-harness-runtime.md
- docs/plugins/codex-harness.md
- docs/tools/btw.md
- extensions/codex/harness.ts
- extensions/codex/index.test.ts
- extensions/codex/media-understanding-provider.test.ts
- extensions/codex/media-understanding-provider.ts
- extensions/codex/src/app-server/attempt-steering.ts
- extensions/codex/src/app-server/attempt-turn-watches.test.ts
- extensions/codex/src/app-server/attempt-turn-watches.ts
- extensions/codex/src/app-server/client.test.ts
- extensions/codex/src/app-server/compact.test.ts
- extensions/codex/src/app-server/compact.ts
- extensions/codex/src/app-server/context-engine-projection.test.ts
- extensions/codex/src/app-server/context-engine-projection.ts
- extensions/codex/src/app-server/dynamic-tool-execution.test.ts
- extensions/codex/src/app-server/dynamic-tools.test.ts
- extensions/codex/src/app-server/dynamic-tools.ts
- extensions/codex/src/app-server/event-projector.test.ts
- extensions/codex/src/app-server/event-projector.ts
- extensions/codex/src/app-server/local-runtime-attribution.ts
- extensions/codex/src/app-server/outcome-fallback-runtime-contract.test.ts
- extensions/codex/src/app-server/protocol-validators.ts
- extensions/codex/src/app-server/protocol.ts
- extensions/codex/src/app-server/run-attempt-test-harness.ts
- extensions/codex/src/app-server/run-attempt.context-engine.test.ts
- extensions/codex/src/app-server/run-attempt.test.ts
- extensions/codex/src/app-server/run-attempt.ts
- extensions/codex/src/app-server/shared-client.test.ts
- extensions/codex/src/app-server/shared-client.ts
- extensions/codex/src/app-server/side-question.test.ts
- extensions/codex/src/app-server/side-question.ts
- extensions/codex/src/app-server/thread-lifecycle.test.ts
- extensions/codex/src/app-server/thread-lifecycle.ts
- extensions/codex/src/app-server/trajectory.test.ts
- extensions/codex/src/app-server/trajectory.ts
- extensions/codex/src/conversation-turn-collector.test.ts
- extensions/codex/test-api.ts
- scripts/generate-prompt-snapshots.ts
- scripts/prompt-snapshot-files.ts
- src/agents/auth-profile-runtime-contract.test.ts
- src/agents/btw.test.ts
- src/agents/btw.ts
- src/agents/cli-output.test.ts
- src/agents/cli-output.ts
- src/agents/cli-runner.before-agent-reply-cron.test.ts
- src/agents/cli-runner.binding-flush.test.ts
- src/agents/cli-runner.context-engine.test.ts
- src/agents/cli-runner.reliability.test.ts
- src/agents/cli-runner.spawn.test.ts
- src/agents/cli-runner.ts
- src/agents/cli-runner/claude-live-session.ts
- src/agents/cli-runner/claude-skills-plugin.ts
- src/agents/cli-runner/execute.supervisor-capture.test.ts
- src/agents/cli-runner/execute.ts
- src/agents/cli-runner/log.ts
- src/agents/cli-runner/prepare.test.ts
- src/agents/cli-runner/prepare.ts
- src/agents/cli-runner/session-history.test.ts
- src/agents/cli-runner/session-history.ts
- src/agents/cli-runner/types.ts
- src/agents/command/attempt-execution.helpers.ts
- src/agents/command/attempt-execution.test.ts
- src/agents/command/claude-cli-project-dir.ts
- src/agents/harness/types.ts
- src/agents/mcp-oauth.ts
- src/agents/model-catalog-browse.test.ts
- src/agents/model-catalog-browse.ts
- src/channels/draft-stream-loop.test.ts
- src/channels/draft-stream-loop.ts
- src/channels/typing-lifecycle.ts
- src/channels/typing.test.ts
- src/channels/typing.ts
- src/commands/doctor-claude-cli.test.ts
- src/commands/doctor-claude-cli.ts
- src/media-understanding/runner.skip-tiny-audio.test.ts
- src/plugin-sdk/agent-harness-runtime.ts
- test/fixtures/agents/prompt-snapshots/codex-runtime-happy-path/README.md
- test/fixtures/agents/prompt-snapshots/codex-runtime-happy-path/codex-dynamic-tools.discord-group.json
- test/fixtures/agents/prompt-snapshots/codex-runtime-happy-path/codex-dynamic-tools.heartbeat-turn.json
- test/fixtures/agents/prompt-snapshots/codex-runtime-happy-path/codex-dynamic-tools.telegram-direct.json
- test/fixtures/agents/prompt-snapshots/codex-runtime-happy-path/discord-group-codex-message-tool.md
- test/fixtures/agents/prompt-snapshots/codex-runtime-happy-path/telegram-direct-codex-message-tool.md
- test/fixtures/agents/prompt-snapshots/codex-runtime-happy-path/telegram-heartbeat-codex-tool.md
- test/helpers/agents/happy-path-prompt-snapshots.ts
- test/helpers/agents/prompt-snapshot-paths.ts
- test/scripts/prompt-snapshots.test.ts
- test/vitest/vitest.channels.config.ts

OpenClaw supports multiple agent runtimes beyond the default internal "Pi" harness. This page documents the integration with the **Codex app-server** (native runtime via JSON-RPC), **CLI Backends** (like `claude-cli` and `opencode`), and the selection logic that determines which backend to use.

## Overview

OpenClaw categorizes its execution environments into three primary types:

1. PI (Internal): The default TypeScript-based agent core that manages tools, memory, and model providers directly.
2. Codex Harness: A native runtime integration that offloads low-level agent logic (model discovery, thread management, compaction) to the codex app-server while keeping OpenClaw as the interface and tool provider.
3. CLI Backends: External command-line agents (e.g., Anthropic's Claude Code) wrapped by OpenClaw to provide them with session persistence, channel connectivity, and MCP bridge support.

### When to Use Each Backend

Sources: [docs/plugins/codex-harness.md10-32](https://github.com/openclaw/openclaw/blob/fbdf5937/docs/plugins/codex-harness.md?plain=1#L10-L32) [extensions/codex/src/app-server/run-attempt.ts32-34](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/codex/src/app-server/run-attempt.ts#L32-L34)

## Codex App-Server Harness

The `codex` plugin allows OpenClaw to run embedded OpenAI agent turns through the native Codex app-server instead of the built-in PI harness [docs/plugins/codex-harness.md10-14](https://github.com/openclaw/openclaw/blob/fbdf5937/docs/plugins/codex-harness.md?plain=1#L10-L14) This integration uses a JSON-RPC 2.0 protocol over Stdio or WebSockets.

### Implementation Architecture

The harness is implemented in `extensions/codex/src/app-server/`. The `runCodexAppServerAttempt` function (aliased via `testing` or exported in internal modules) serves as the entry point for executing a turn via this backend [extensions/codex/src/app-server/run-attempt.ts60-61](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/codex/src/app-server/run-attempt.ts#L60-L61)

#### Data Flow: Natural Language to Codex RPC

The following diagram illustrates how a user message moves from a channel into the native Codex runtime, utilizing the projector to handle the asynchronous stream of events.

**Codex Runtime Data Flow**

```

```

Sources: [extensions/codex/src/app-server/run-attempt.ts61-125](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/codex/src/app-server/run-attempt.ts#L61-L125) [extensions/codex/src/app-server/event-projector.ts1-12](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/codex/src/app-server/event-projector.ts#L1-L12) [extensions/codex/src/app-server/client.ts118](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/codex/src/app-server/client.ts#L118-L118)

### Key Components

- CodexAppServerClient : Interface for the underlying process or WebSocket connection. It handles requests and notifications between OpenClaw and the app-server extensions/codex/src/app-server/client.ts 118
- CodexAppServerEventProjector : A stateful class that translates native Codex notifications (e.g., item/reasoning/textDelta ) into OpenClaw agent events extensions/codex/src/app-server/event-projector.ts 144-196
- Thread Lifecycle : Managed via startOrResumeThread . It handles native thread resume by checking readCodexAppServerBinding and evaluating if existing threads are compatible with current config extensions/codex/src/app-server/thread-lifecycle.ts 224-229
- Dynamic Tool Bridge : The createCodexDynamicToolBridge function allows the native Codex agent to call OpenClaw tools via JSON-RPC extensions/codex/src/app-server/dynamic-tools.ts 32-33

Sources: [extensions/codex/src/app-server/client.ts118](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/codex/src/app-server/client.ts#L118-L118) [extensions/codex/src/app-server/event-projector.ts144-196](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/codex/src/app-server/event-projector.ts#L144-L196) [extensions/codex/src/app-server/thread-lifecycle.ts224-229](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/codex/src/app-server/thread-lifecycle.ts#L224-L229) [extensions/codex/src/app-server/dynamic-tools.ts32-33](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/codex/src/app-server/dynamic-tools.ts#L32-L33)

## CLI Backends

CLI backends allow OpenClaw to wrap external agent binaries (e.g., `claude-cli`), providing them with session management and channel connectivity.

### Execution Pipeline

The `runCliAgent` execution logic (in `src/agents/cli-runner.ts`) handles process management, including argument parsing and output streaming.

1. Preparation : prepareCliRunContext (referenced in types.ts ) resolves the workspace, environment variables, and auth credentials src/agents/cli-runner/types.ts 13
2. Execution : The runner spawns the process using a ProcessSupervisor (internal to CLI runner logic). It supports both stdin and arg input modes.
3. Reliability : CLI-backed runtimes include logic to recover from interrupted tool calls and stale session bindings CHANGELOG.md 9

**CLI Backend Execution Diagram**

```

```

Sources: [src/agents/cli-runner.ts10-13](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/cli-runner.ts#L10-L13) [src/agents/cli-runner.ts189-198](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/cli-runner.ts#L189-L198) [CHANGELOG.md9](https://github.com/openclaw/openclaw/blob/fbdf5937/CHANGELOG.md?plain=1#L9-L9)

### Session Persistence

CLI backends often require transcript flushing to maintain state. The `isCliBindingFlushed` function checks if external transcripts (like `claude-cli` session files) have been successfully written to disk before proceeding [src/agents/cli-runner.ts83-103](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/cli-runner.ts#L83-L103)

## Agent Runtime Selection

OpenClaw determines the backend based on model references and configuration.

1. Automatic Interception : The codex plugin intercepts openai/gpt-* model refs to use the app-server harness if enabled docs/plugins/codex-harness.md 57-60
2. Context Engine Projection : When a context engine like Lossless is used, Codex turns rehydrate from the engine's summary extensions/codex/src/app-server/thread-lifecycle.ts 86-90
3. Explicit Routing : Users can force a runtime by setting agentRuntime.id: "codex" or "pi" in provider or model config docs/plugins/codex-harness.md 117-118

Sources: [docs/plugins/codex-harness.md57-60](https://github.com/openclaw/openclaw/blob/fbdf5937/docs/plugins/codex-harness.md?plain=1#L57-L60) [extensions/codex/src/app-server/thread-lifecycle.ts86-90](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/codex/src/app-server/thread-lifecycle.ts#L86-L90) [docs/plugins/codex-harness.md117-118](https://github.com/openclaw/openclaw/blob/fbdf5937/docs/plugins/codex-harness.md?plain=1#L117-L118)

## Harness Plugin Architecture

The harness system allows the `codex` extension to contribute capabilities to the Gateway.

### Native Hook Relay

The Codex harness implements a `NativeHookRelay` to bridge native events into OpenClaw's hook system [extensions/codex/src/app-server/run-attempt.ts182-188](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/codex/src/app-server/run-attempt.ts#L182-L188)

- Compaction : Triggers before_compaction and after_compaction hooks when the app-server flushes context extensions/codex/src/app-server/event-projector.ts 10-12
- LLM I/O : Intercepts native inputs/outputs for auditing via runAgentHarnessLlmInputHook and runAgentHarnessLlmOutputHook extensions/codex/src/app-server/run-attempt.ts 26-27

### Transcript Mirroring

To maintain consistency, `readMirroredSessionHistoryMessages` synchronizes native app-server state with OpenClaw's session files [extensions/codex/src/app-server/run-attempt.ts63](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/codex/src/app-server/run-attempt.ts#L63-L63) This ensures the visible chat history reflects the native agent's internal state accurately.

### Compaction & Context Engines

The Codex harness handles compaction natively unless a context engine is active [docs/plugins/codex-harness.md128-133](https://github.com/openclaw/openclaw/blob/fbdf5937/docs/plugins/codex-harness.md?plain=1#L128-L133) If the native Codex thread binding is missing or stale, OpenClaw attempts recovery or repair [docs/plugins/codex-harness.md149-150](https://github.com/openclaw/openclaw/blob/fbdf5937/docs/plugins/codex-harness.md?plain=1#L149-L150)

**Compaction Lifecycle**

```

```

Sources: [extensions/codex/src/app-server/run-attempt.ts74-75](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/codex/src/app-server/run-attempt.ts#L74-L75) [extensions/codex/src/app-server/event-projector.ts10-12](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/codex/src/app-server/event-projector.ts#L10-L12) [extensions/codex/src/app-server/thread-lifecycle.ts50-51](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/codex/src/app-server/thread-lifecycle.ts#L50-L51)

Sources: [extensions/codex/src/app-server/run-attempt.ts26-27](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/codex/src/app-server/run-attempt.ts#L26-L27) [extensions/codex/src/app-server/event-projector.ts10-12](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/codex/src/app-server/event-projector.ts#L10-L12) [extensions/codex/src/app-server/run-attempt.ts182-188](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/codex/src/app-server/run-attempt.ts#L182-L188) [docs/plugins/codex-harness.md128-133](https://github.com/openclaw/openclaw/blob/fbdf5937/docs/plugins/codex-harness.md?plain=1#L128-L133)
