System-Prompt (System Prompt)

源码版本rust-v0.145.0

codex zerlegt „was dem Modell gesagt wird" in mehrere statische Texte, Templates und Kontextfragmente, die zusammengesetzt werden. Der Crate prompts liefert Konstanten und Templates; core wählt beim Session-Start die base instructions des jeweiligen Modells und schichtet AGENTS.md, permissions instructions und Persönlichkeits-Fragmente darüber, um den finalen System-Prompt zu bilden. Diese Seite behandelt diese Aufbaukette.

Verantwortlichkeiten

1. Standard-base-instructions und Personality-Templates pro Modell verwalten, nach Modell-Slug ausgewählt und gefüllt: codex-rs/protocol/src/openai_models.rs:478-500
2. Konstante Werkzeug-/Approval-Hinweise exponieren (apply_patch, compaction, review, permissions, realtime): codex-rs/prompts/src/lib.rs:1-27
3. Aus AGENTS.md und Nutzeranweisungen projektbezogene Developer-Instructions zusammenbauen: codex-rs/core/src/agents_md.rs:53-80
4. Sandbox-/Approval-Policy zu modell-sichtbaren permission instructions rendern: codex-rs/prompts/src/permissions_instructions.rs:62-117
5. base_instructions beim Session-Start und Turn-Wechsel festlegen und client/compact zur Verfügung stellen: codex-rs/core/src/session/mod.rs:615-631

Entwurfsbeweggründe

Die base instructions dürfen nicht hart in core codiert sein. Verschiedene Modelle (gpt-5.1, gpt-5.2-codex usw.) haben unterschiedliche Standardpersönlichkeiten und Werkzeugbeschreibungen; dasselbe Modell kann zusätzlich die Personality wechseln (friendly/pragmatic/none). Die Templates liegen in models-manager und core/templates/; ModelMessages.instructions_template ersetzt zur Laufzeit den Platzhalter , sodass ein neues Modell nur eine neue Markdown-Datei braucht und core unangetastet bleibt.

Ein weiteres Motiv ist Provenienz (Rückverfolgbarkeit der Herkunft). AGENTS.md kann auf Nutzerebene, am Projekt-Root oder in Unterverzeichnissen liegen; bei mehrschichtigem Aufbau bewahrt LoadedAgentsMd für jeden Eintrag die Herkunft und taggt die Ausgabe bei Bedarf nach Environment, damit das Modell weiß, welcher Abschnitt aus welchem Verzeichnis stammt. Permission instructions verhalten sich analog — sie sind keine gewöhnliche Zeichenkette, sondern ein ContextualUserFragment mit <permissions instructions>-Marker, damit der Kontextmanager sie bei Kompression (compaction) oder Replay erkennt und abtrennt.

Wichtige Dateien

• codex-rs/prompts/src/lib.rs:1-27 — Einstieg des prompts-Crates; re-exportiert APPLY_PATCH_TOOL_INSTRUCTIONS, SUMMARIZATION_PROMPT, REVIEW_PROMPT, BACKEND_PROMPT usw.
• codex-rs/prompts/src/permissions_instructions.rs:62-117 — PermissionsInstructions rendert PermissionProfile + Policy in einen modell-sichtbaren Developer-Abschnitt.
• codex-rs/core/src/agents_md.rs:253-345 — LoadedAgentsMd und legacy_text(); geordnete Aneinanderreihung der Projektanweisungen.
• codex-rs/core/src/session/mod.rs:615-631 — Drei-stufiger Fallback der base_instructions: Config-Override → Historien-Snapshot → Modell-Standard.
• codex-rs/core/src/session/mod.rs:1224-1229 — get_base_instructions wird während Turn-Verarbeitung und Compaction wiederholt aufgerufen.
• codex-rs/protocol/src/openai_models.rs:478-500 — get_model_instructions zieht Template-Ersetzung des Personality-Platzhalters vor.
• codex-rs/models-manager/src/model_info.rs:17-22 — Konstante BASE_INSTRUCTIONS,加上 personality section header/placeholder.
• codex-rs/core/src/client.rs:849-864 — client baut beim Request base_instructions und tools in messages ein.

Drei-stufiger Fallback der base_instructions — zuerst Nutzer-Config, dann Wiederherstellung aus der Konversationshistorie, zuletzt Modell-Standard.

let base_instructions = config
    .base_instructions
    .clone()
    .or_else(|| conversation_history.get_base_instructions().map(|s| s.text))
    .unwrap_or_else(|| model_info.get_model_instructions(config.personality));

Template-Ersetzung der Personality: Hat das Modell ein instructions_template, wird immer per Template ersetzt; ohne Template fällt es auf base_instructions zurück.

pub fn get_model_instructions(&self, personality: Option<Personality>) -> String {
    if let Some(model_messages) = &self.model_messages
        && let Some(template) = &model_messages.instructions_template
    {
        let personality_message = model_messages
            .get_personality_message(personality)
            .unwrap_or_default();
        template.replace(PERSONALITY_PLACEHOLDER, personality_message.as_str())
    } else {
        // ...
        self.base_instructions.clone()
    }
}

Permission instructions sind keine gewöhnliche Zeichenkette, sondern ein marker-tragendes ContextualUserFragment, damit der Kontextmanager sie bei Kompression oder Replay erkennt und abtrennt.

impl ContextualUserFragment for PermissionsInstructions {
    fn role(&self) -> &'static str { "developer" }
    fn markers(&self) -> (&'static str, &'static str) { Self::type_markers() }
    fn type_markers() -> (&'static str, &'static str) {
        ("<permissions instructions>", "</permissions instructions>")
    }
    fn body(&self) -> String { PermissionsInstructions::body(self) }
}

Datenfluss

Grenzen und Fehler

• Hat ein Modell kein instructions_template, aber friendly/pragmatic personality angefordert, fällt es auf base instructions zurück und schreibt einen Trace-Eintrag: codex-rs/protocol/src/openai_models.rs:488-498
• Bei config.personality == None löscht with_config_overrides das model_messages, damit der Personality-Abschnitt nicht fälschlich injiziert wird: codex-rs/models-manager/src/model_info.rs:56-70
• PermissionsInstructions.from_permission_profile verlangt eine execpolicy::Policy-Referenz — fehlt die Policy, passen Approval-Hinweis und tatsächliche Blockierung nicht zusammen: codex-rs/prompts/src/permissions_instructions.rs:89-117
• Beim Turn-Wechsel wird, wenn die base_instructions mit dem Standard-Personality-Template des Modells übereinstimmt, die wiederholte Injektion der Personality-Nachricht übersprungen: codex-rs/core/src/session/mod.rs:3244-3257
• In Multi-Environment-Situationen nimmt LoadedAgentsMd.text den Pfad environment_labeled_text statt legacy_text, damit Anweisungen aus verschiedenen cwd nicht zu einem ununterscheidbaren Block verschmelzen: codex-rs/core/src/agents_md.rs:311-345

Zusammenfassung

Der System-Prompt ist in codex kein hartkodierter String, sondern ein drei-stufiger Fallback Modell-Standard → Config-Override → Historien-Snapshot, ergänzt um markierte Fragmente wie AGENTS.md, permissions instructions und personality. Der Crate prompts nimmt nur Konstanten und Templates auf; die Aufbaulogik steckt in core; der Aufrufer erhält ein BaseInstructions, das schon die festgelegte Zeichenkette ist. Diese Kette zu verstehen, ist wichtig, um in der Agent-Hauptschleife „warum antwortet das Modell so" und in der Kompression (compaction) „welche Abschnitte werden abgetrennt und wieder eingespielt" zu debuggen.