Codex-Harness

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Schnellkonfiguration

openclaw models auth login --provider openai-codex

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
      },
    },
  },
  agents: {
    defaults: {
      model: "openai/gpt-5.5",
      agentRuntime: {
        id: "codex",
      },
    },
  },
}

{
  plugins: {
    allow: ["codex"],
    entries: {
      codex: {
        enabled: true,
      },
    },
  },
}

​

Was dieses Plugin ändert

• direkte OpenAI-API-Key-Oberflächen wie Bilder, Embeddings, Sprache oder Realtime zu ersetzen
• openai-codex/*-Modellreferenzen ohne openclaw doctor --fix zu konvertieren
• ACP/acpx zum Standard-Codex-Pfad zu machen
• vorhandene Sitzungen, die bereits eine PI-Runtime aufgezeichnet haben, im laufenden Betrieb umzuschalten
• OpenClaw-Kanalzustellung, Sitzungsdateien, Auth-Profil-Speicherung oder Nachrichtenrouting zu ersetzen

• before_prompt_build
• before_compaction, after_compaction
• llm_input, llm_output
• before_tool_call, after_tool_call
• before_message_write für gespiegelte Transkriptdatensätze
• before_agent_finalize über Codex-Stop-Weiterleitung
• agent_end

​

Routenübersicht

• openai-codex/* ist eine Legacy-Route, die Doctor umschreibt.
• agentRuntime.id: "codex" erfordert das Codex-Harness und schlägt geschlossen fehl, wenn es nicht verfügbar ist.
• agentRuntime.id: "auto" lässt registrierte Harnesses passende Provider-Routen beanspruchen; OpenAI-Agent-Referenzen werden zu Codex statt PI aufgelöst.
• /codex ... beantwortet „welche native Codex-Unterhaltung soll dieser Chat binden oder steuern?“
• ACP beantwortet „welchen externen Harness-Prozess soll acpx starten?“

​

Das richtige Modellpräfix wählen

​

Was Doctor-Warnungen bedeuten

• openai/<model>
• agentRuntime.id: "codex"

​

Anforderungen

• OpenClaw mit verfügbarem gebündeltem codex-Plugin.
• Codex App-Server 0.125.0 oder neuer. Das gebündelte Plugin verwaltet standardmäßig eine kompatible Codex App-Server-Binärdatei, daher wirken sich lokale codex-Befehle auf dem PATH nicht auf den normalen Harness-Start aus.
• Codex-Authentifizierung, die dem App-Server-Prozess oder der Codex-Auth-Bridge von OpenClaw zur Verfügung steht. Lokale App-Server-Starts verwenden für jeden Agent ein von OpenClaw verwaltetes Codex-Home und ein isoliertes untergeordnetes HOME, sodass sie standardmäßig weder Ihr persönliches ~/.codex-Konto noch Skills, Plugins, Konfiguration, Thread-Zustand oder natives $HOME/.agents/skills lesen.

​

Workspace-Bootstrap-Dateien

​

Codex neben anderen Modellen hinzufügen

• Legen Sie Codex auf einen dedizierten Agent mit agentRuntime.id: "codex".
• Behalten Sie den Standard-Agent auf agentRuntime.id: "auto" und den PI-Fallback für normale gemischte Provider-Nutzung bei.
• Verwenden Sie alte codex/*-Refs nur aus Kompatibilitätsgründen. Neue Konfigurationen sollten openai/* plus eine explizite Codex-Laufzeitrichtlinie bevorzugen.

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
      },
    },
  },
  agents: {
    defaults: {
      agentRuntime: {
        id: "auto",
      },
    },
    list: [
      {
        id: "main",
        default: true,
        model: "anthropic/claude-opus-4-6",
      },
      {
        id: "codex",
        name: "Codex",
        model: "openai/gpt-5.5",
        agentRuntime: {
          id: "codex",
        },
      },
    ],
  },
}

• Der Standard-Agent main verwendet den normalen Provider-Pfad und den PI-Kompatibilitäts-Fallback.
• Der Agent codex verwendet den Codex App-Server-Harness.
• Wenn Codex für den Agent codex fehlt oder nicht unterstützt wird, schlägt die Runde fehl, statt stillschweigend PI zu verwenden.

​

Agent-Befehlsrouting

​

Nur-Codex-Bereitstellungen

{
  agents: {
    defaults: {
      model: "openai/gpt-5.5",
      agentRuntime: {
        id: "codex",
      },
    },
  },
}

OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run

​

Codex pro Agent

{
  agents: {
    defaults: {
      agentRuntime: {
        id: "auto",
      },
    },
    list: [
      {
        id: "main",
        default: true,
        model: "anthropic/claude-opus-4-6",
      },
      {
        id: "codex",
        name: "Codex",
        model: "openai/gpt-5.5",
        agentRuntime: {
          id: "codex",
        },
      },
    ],
  },
}

​

Modellerkennung

• GPT-5.5
• GPT-5.4 mini
• GPT-5.2

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          discovery: {
            enabled: true,
            timeoutMs: 2500,
          },
        },
      },
    },
  },
}

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          discovery: {
            enabled: false,
          },
        },
      },
    },
  },
}

​

App-Server-Verbindung und Richtlinie

codex app-server --listen stdio://

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          appServer: {
            mode: "guardian",
            serviceTier: "fast",
          },
        },
      },
    },
  },
}

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          appServer: {
            transport: "websocket",
            url: "ws://127.0.0.1:39175",
            authToken: "${CODEX_APP_SERVER_TOKEN}",
            requestTimeoutMs: 60000,
          },
        },
      },
    },
  },
}

openclaw migrate codex --dry-run
openclaw migrate apply codex --yes

1. Ein explizites OpenClaw-Codex-Auth-Profil für den Agent.
2. Das vorhandene Konto des App-Servers im Codex-Home dieses Agents.
3. Nur für lokale stdio-App-Server-Starts: CODEX_API_KEY, dann OPENAI_API_KEY, wenn kein App-Server-Konto vorhanden ist und OpenAI-Authentifizierung weiterhin erforderlich ist.

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          appServer: {
            clearEnv: ["CODEX_API_KEY", "OPENAI_API_KEY"],
          },
        },
      },
    },
  },
}

• OPENCLAW_CODEX_APP_SERVER_BIN
• OPENCLAW_CODEX_APP_SERVER_ARGS
• OPENCLAW_CODEX_APP_SERVER_MODE=yolo|guardian
• OPENCLAW_CODEX_APP_SERVER_APPROVAL_POLICY
• OPENCLAW_CODEX_APP_SERVER_SANDBOX

​

Computernutzung

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          computerUse: {
            autoInstall: true,
          },
        },
      },
    },
  },
  agents: {
    defaults: {
      model: "openai/gpt-5.5",
      agentRuntime: {
        id: "codex",
      },
    },
  },
}

• /codex computer-use status
• /codex computer-use install
• /codex computer-use install --source <marketplace-source>
• /codex computer-use install --marketplace-path <path>

​

Häufige Rezepte

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
      },
    },
  },
}

{
  agents: {
    defaults: {
      model: "openai/gpt-5.5",
      agentRuntime: {
        id: "codex",
      },
    },
  },
  plugins: {
    entries: {
      codex: {
        enabled: true,
      },
    },
  },
}

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          appServer: {
            mode: "guardian",
            approvalPolicy: "on-request",
            approvalsReviewer: "auto_review",
            sandbox: "workspace-write",
          },
        },
      },
    },
  },
}

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          appServer: {
            transport: "websocket",
            url: "ws://gateway-host:39175",
            headers: {
              "X-OpenClaw-Agent": "main",
            },
          },
        },
      },
    },
  },
}

​

Codex-Befehl

• /codex status zeigt die Live-Konnektivität zum App-Server, Modelle, Konto, Ratenlimits, MCP-Server und Skills.
• /codex models listet Live-Modelle des Codex-App-Servers auf.
• /codex threads [filter] listet aktuelle Codex-Threads auf.
• /codex resume <thread-id> verbindet die aktuelle OpenClaw-Sitzung mit einem vorhandenen Codex-Thread.
• /codex compact fordert den Codex-App-Server auf, den verbundenen Thread zu komprimieren.
• /codex review startet die native Codex-Review für den verbundenen Thread.
• /codex diagnostics [note] fragt nach, bevor Codex-Diagnosefeedback für den verbundenen Thread gesendet wird.
• /codex computer-use status prüft das konfigurierte Computer Use-Plugin und den MCP-Server.
• /codex computer-use install installiert das konfigurierte Computer Use-Plugin und lädt MCP-Server neu.
• /codex account zeigt Konto- und Ratenlimitstatus an.
• /codex mcp listet den MCP-Serverstatus des Codex-App-Servers auf.
• /codex skills listet Skills des Codex-App-Servers auf.

​

Allgemeiner Debugging-Workflow

1. Führen Sie /diagnostics bad tool choice after image upload oder eine andere kurze Notiz aus, die beschreibt, was Sie gesehen haben.
2. Genehmigen Sie die Diagnoseanfrage einmal. Die Genehmigung erstellt die lokale Gateway-Diagnose-ZIP-Datei und sendet, da die Sitzung den Codex-Harness verwendet, außerdem das relevante Codex-Feedbackpaket an OpenAI-Server.
3. Kopieren Sie die abgeschlossene Diagnoseantwort in den Fehlerbericht oder Support-Thread. Sie enthält den lokalen Bundle-Pfad, eine Datenschutz-Zusammenfassung, OpenClaw-Sitzungs-IDs, Codex-Thread-IDs und eine Zeile Inspect locally für jeden Codex-Thread.
4. Wenn Sie den Lauf selbst debuggen möchten, führen Sie den ausgegebenen Befehl Inspect locally in einem Terminal aus. Er sieht wie codex resume <thread-id> aus und öffnet den nativen Codex-Thread, damit Sie die Unterhaltung prüfen, lokal fortsetzen oder Codex fragen können, warum ein bestimmtes Tool oder ein bestimmter Plan gewählt wurde.

​

Einen Codex-Thread über die CLI prüfen

codex resume <thread-id>

​

Hook-Grenzen

​

V1-Supportvertrag

​

Tools, Medien und Compaction

​

Fehlerbehebung

​

Verwandt

• Agent-Harness-Plugins
• Agent-Runtimes
• Modell-Provider
• OpenAI-Provider
• Status
• Plugin-Hooks
• Konfigurationsreferenz
• Testen