Skip to content

Commit 2a0350b

Browse files
100yenadminEva (agent)steipete
authored
Separate prompt surfaces by selected harness (#83454)
* fix: scope agent prompt surfaces * fix(codex): preserve lightweight project doc suppression * fix(codex): demote openclaw context for native turns * fix(codex): report demoted prompt context * fix(codex): align demoted prompt observability * docs: format codex runtime table * docs: align codex prompt overlay docs * test: align codex prompt snapshots * test: update prompt snapshot contract --------- Co-authored-by: Eva (agent) <[email protected]> Co-authored-by: Peter Steinberger <[email protected]>
1 parent 3132969 commit 2a0350b

39 files changed

Lines changed: 1051 additions & 434 deletions

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ Docs: https://docs.openclaw.ai
1717
- Skills: rename the repo-local Codex closeout review skill and helper to `autoreview` while preserving the Codex-first fallback behavior.
1818
- Skills: add a meme-maker skill for curated template search, local SVG/PNG rendering, Imgflip hosted rendering, and Know Your Meme provenance links.
1919
- Browser: surface pending and recently handled modal dialogs in snapshots, return `blockedByDialog` when an action opens a modal, and allow `browser dialog --dialog-id` to answer pending dialogs.
20+
- Codex app-server: scope OpenClaw prompt guidance by runtime surface so native Codex keeps Codex-owned base/personality instructions while OpenClaw contributes only runtime context, delivery guidance, and explicitly scoped command hints. (#83454) Thanks @100yenadmin.
2021
- Agents/tools: shorten built-in tool descriptions and schema hints across media, messaging, sessions, cron, Gateway, web, image/PDF, TTS, nodes, and plan tools while preserving routing guardrails.
2122
- Skills: add node inspector debugging, fused diagram generation, and throwaway spike workflow skills.
2223
- CLI/plugins: add `defineToolPlugin` plus `openclaw plugins build`, `validate`, and `init` for typed simple tool plugins with generated manifest metadata, optional tool declarations, and context factories.

‎docs/.generated/plugin-sdk-api-baseline.sha256‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,2 @@
1-
048d8ff5e4455d16f75f6762a916f67c982e1211fb7085456647234255567466 plugin-sdk-api-baseline.json
2-
2d46a9660c9143f823a47df3c7ecfd315a4999e96af5eddb4ba4e71d9bb377a6 plugin-sdk-api-baseline.jsonl
1+
efac86567bddd0beafacae3657b69b13a242796419097f0398e9e4ebfa3249dc plugin-sdk-api-baseline.json
2+
bf676f45626ef93026c4410a8a7d5f010543814da3f6246885fd8c95a7b9901e plugin-sdk-api-baseline.jsonl

‎docs/gateway/config-agents.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -554,7 +554,7 @@ Replace the entire OpenClaw-assembled system prompt with a fixed string. Set at
554554

555555
### `agents.defaults.promptOverlays`
556556

557-
Provider-independent prompt overlays applied by model family. GPT-5-family model ids receive the shared behavior contract across providers; `personality` controls only the friendly interaction-style layer.
557+
Provider-independent prompt overlays applied by model family on OpenClaw-assembled prompt surfaces. GPT-5-family model ids receive the shared behavior contract across PI/provider routes; `personality` controls only the friendly interaction-style layer. Native Codex app-server routes keep Codex-owned base/model/personality instructions instead of this OpenClaw GPT-5 overlay.
558558

559559
```json5
560560
{

‎docs/plugins/codex-harness-reference.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -363,9 +363,9 @@ filenames for persona files, because Codex fallbacks only apply when
363363
For OpenClaw workspace parity, the Codex harness resolves the other bootstrap
364364
files, including `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`,
365365
`HEARTBEAT.md`, `BOOTSTRAP.md`, and `MEMORY.md` when present, and forwards them
366-
through Codex developer instructions on `thread/start` and `thread/resume`.
367-
This keeps workspace persona and profile context visible on the native Codex
368-
behavior-shaping lane without duplicating `AGENTS.md`.
366+
as OpenClaw turn input reference context. This keeps workspace persona and
367+
profile context visible to the native Codex turn without promoting it above
368+
Codex-owned system/developer instructions or duplicating `AGENTS.md`.
369369

370370
## Environment overrides
371371

‎docs/plugins/codex-harness-runtime.md‎

Lines changed: 27 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,20 @@ Codex owns the canonical native thread, native model loop, native tool
2323
continuation, and native compaction unless the active OpenClaw context engine
2424
declares that it owns compaction.
2525

26+
Prompt routing follows the selected runtime, not just the provider string. A
27+
native Codex turn receives Codex app-server developer instructions, while an
28+
explicit PI compatibility route keeps the normal OpenClaw/PI system prompt even
29+
when it uses Codex-flavored OpenAI auth or transport.
30+
31+
Native Codex keeps Codex-owned base/model/personality instructions and
32+
project-doc behavior according to the active Codex thread config. Lightweight
33+
OpenClaw runs still preserve their existing project-doc suppression. OpenClaw
34+
developer instructions are limited to OpenClaw runtime concerns such as
35+
source-channel delivery, OpenClaw dynamic tools, ACP delegation, and adapter
36+
context. OpenClaw skill catalogs and non-AGENTS
37+
workspace bootstrap files are projected as turn input reference context for
38+
native Codex instead of being promoted into Codex developer instructions.
39+
2640
## Thread bindings and model changes
2741

2842
When an OpenClaw session is attached to an existing Codex thread, the next turn
@@ -100,19 +114,19 @@ They do not invoke OpenClaw plugin hooks.
100114

101115
Supported in Codex runtime v1:
102116

103-
| Surface | Support | Why |
104-
| --------------------------------------------- | -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
105-
| OpenAI model loop through Codex | Supported | Codex app-server owns the OpenAI turn, native thread resume, and native tool continuation. |
106-
| OpenClaw channel routing and delivery | Supported | Telegram, Discord, Slack, WhatsApp, iMessage, and other channels stay outside the model runtime. |
107-
| OpenClaw dynamic tools | Supported | Codex asks OpenClaw to execute these tools, so OpenClaw stays in the execution path. |
108-
| Prompt and context plugins | Supported | OpenClaw builds prompt overlays and projects context into the Codex turn before starting or resuming the thread. |
109-
| Context engine lifecycle | Supported | Assemble, ingest, after-turn maintenance, and context-engine compaction coordination run for Codex turns. |
110-
| Dynamic tool hooks | Supported | `before_tool_call`, `after_tool_call`, and tool-result middleware run around OpenClaw-owned dynamic tools. |
111-
| Lifecycle hooks | Supported as adapter observations | `llm_input`, `llm_output`, `agent_end`, `before_compaction`, and `after_compaction` fire with honest Codex-mode payloads. |
112-
| Final-answer revision gate | Supported through native hook relay | Codex `Stop` is relayed to `before_agent_finalize`; `revise` asks Codex for one more model pass before finalization. |
113-
| Native shell, patch, and MCP block or observe | Supported through native hook relay | Codex `PreToolUse` and `PostToolUse` are relayed for committed native tool surfaces, including MCP payloads on Codex app-server `0.125.0` or newer. Blocking is supported; argument rewriting is not. |
114-
| Native permission policy | Supported through Codex app-server approvals and compatibility native hook relay | Codex app-server approval requests route through OpenClaw after Codex review. The `PermissionRequest` native hook relay is opt-in for native approval modes because Codex emits it before guardian review. |
115-
| App-server trajectory capture | Supported | OpenClaw records the request it sent to app-server and the app-server notifications it receives. |
117+
| Surface | Support | Why |
118+
| --------------------------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
119+
| OpenAI model loop through Codex | Supported | Codex app-server owns the OpenAI turn, native thread resume, and native tool continuation. |
120+
| OpenClaw channel routing and delivery | Supported | Telegram, Discord, Slack, WhatsApp, iMessage, and other channels stay outside the model runtime. |
121+
| OpenClaw dynamic tools | Supported | Codex asks OpenClaw to execute these tools, so OpenClaw stays in the execution path. |
122+
| Prompt and context plugins | Supported | OpenClaw projects OpenClaw-specific prompt/context into the Codex turn while leaving Codex-owned base, model, personality, and configured project-doc prompts in the native Codex lane. Native Codex developer instructions accept only command guidance explicitly scoped to `codex_app_server`; legacy global command hints remain for non-Codex prompt surfaces. |
123+
| Context engine lifecycle | Supported | Assemble, ingest, after-turn maintenance, and context-engine compaction coordination run for Codex turns. |
124+
| Dynamic tool hooks | Supported | `before_tool_call`, `after_tool_call`, and tool-result middleware run around OpenClaw-owned dynamic tools. |
125+
| Lifecycle hooks | Supported as adapter observations | `llm_input`, `llm_output`, `agent_end`, `before_compaction`, and `after_compaction` fire with honest Codex-mode payloads. |
126+
| Final-answer revision gate | Supported through native hook relay | Codex `Stop` is relayed to `before_agent_finalize`; `revise` asks Codex for one more model pass before finalization. |
127+
| Native shell, patch, and MCP block or observe | Supported through native hook relay | Codex `PreToolUse` and `PostToolUse` are relayed for committed native tool surfaces, including MCP payloads on Codex app-server `0.125.0` or newer. Blocking is supported; argument rewriting is not. |
128+
| Native permission policy | Supported through Codex app-server approvals and compatibility native hook relay | Codex app-server approval requests route through OpenClaw after Codex review. The `PermissionRequest` native hook relay is opt-in for native approval modes because Codex emits it before guardian review. |
129+
| App-server trajectory capture | Supported | OpenClaw records the request it sent to app-server and the app-server notifications it receives. |
116130

117131
Not supported in Codex runtime v1:
118132

‎docs/plugins/sdk-overview.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -120,6 +120,26 @@ Plugin commands can set `agentPromptGuidance` when the agent needs a short,
120120
command-owned routing hint. Keep that text about the command itself; do not add
121121
provider- or plugin-specific policy to core prompt builders.
122122

123+
Guidance entries may be legacy strings, which apply to every prompt surface, or
124+
structured entries:
125+
126+
```ts
127+
agentPromptGuidance: [
128+
"Global command hint.",
129+
{ text: "Only show this in the main PI prompt.", surfaces: ["pi_main"] },
130+
];
131+
```
132+
133+
Structured `surfaces` may include `pi_main`, `codex_app_server`, `cli_backend`,
134+
`acp_backend`, or `subagent`. Omit `surfaces` for intentional all-surface
135+
guidance. Do not pass an empty `surfaces` array; it is rejected so accidental
136+
scope loss does not become global prompt text.
137+
138+
Native Codex app-server developer instructions are stricter than other prompt
139+
surfaces: only guidance explicitly scoped to `codex_app_server` is promoted into
140+
that higher-priority lane. Legacy string guidance and unscoped structured
141+
guidance remain available to non-Codex prompt surfaces for compatibility.
142+
123143
### Infrastructure
124144

125145
| Method | What it registers |

‎docs/providers/openai.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -535,11 +535,11 @@ See [Video Generation](/tools/video-generation) for shared tool parameters, prov
535535

536536
## GPT-5 prompt contribution
537537

538-
OpenClaw adds a shared GPT-5 prompt contribution for GPT-5-family runs across providers. It applies by model id, so `openai/gpt-5.5`, legacy pre-repair refs such as `openai-codex/gpt-5.5`, `openrouter/openai/gpt-5.5`, `opencode/gpt-5.5`, and other compatible GPT-5 refs receive the same overlay. Older GPT-4.x models do not.
538+
OpenClaw adds a shared GPT-5 prompt contribution for GPT-5-family runs on OpenClaw-assembled prompt surfaces. It applies by model id, so PI/provider routes such as legacy pre-repair refs (`openai-codex/gpt-5.5`), `openrouter/openai/gpt-5.5`, `opencode/gpt-5.5`, and other compatible GPT-5 refs receive the same overlay. Older GPT-4.x models do not.
539539

540-
The bundled native Codex harness uses the same GPT-5 behavior and heartbeat overlay through Codex app-server developer instructions, so `openai/gpt-5.x` sessions routed through Codex keep the same follow-through and proactive heartbeat guidance even though Codex owns the rest of the harness prompt.
540+
The bundled native Codex harness does not receive this OpenClaw GPT-5 overlay through Codex app-server developer instructions. Native Codex keeps Codex-owned base, model, personality, and project-doc behavior; OpenClaw contributes only runtime context such as channel delivery, OpenClaw dynamic tools, ACP delegation, workspace context, and OpenClaw skills.
541541

542-
The GPT-5 contribution adds a tagged behavior contract for persona persistence, execution safety, tool discipline, output shape, completion checks, and verification. Channel-specific reply and silent-message behavior stays in the shared OpenClaw system prompt and outbound delivery policy. The GPT-5 guidance is always enabled for matching models. The friendly interaction-style layer is separate and configurable.
542+
The GPT-5 contribution adds a tagged behavior contract for persona persistence, execution safety, tool discipline, output shape, completion checks, and verification on matching OpenClaw-assembled prompts. Channel-specific reply and silent-message behavior stays in the shared OpenClaw system prompt and outbound delivery policy. The friendly interaction-style layer is separate and configurable.
543543

544544
| Value | Effect |
545545
| ---------------------- | ------------------------------------------- |

0 commit comments

Comments
 (0)