Skip to content

Commit e0d1a2a

Browse files
pash-openaipash-openai
authored
Move Codex soul context to developer instructions (#84331)
* Move Codex soul context to developer instructions * Route Codex workspace context by lifetime * Refresh Codex prompt snapshots * Update prompt snapshot expectations * Fix Codex workspace context diagnostics
1 parent 68c5a89 commit e0d1a2a

16 files changed

Lines changed: 634 additions & 195 deletions

‎docs/concepts/soul.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -105,10 +105,10 @@ Sharp is good. Annoying is not.
105105

106106
<CardGroup cols={2}>
107107
<Card title="Agent workspace" href="/concepts/agent-workspace" icon="folder-open">
108-
Workspace files OpenClaw injects into the system prompt.
108+
Workspace files OpenClaw injects into model context.
109109
</Card>
110110
<Card title="System prompt" href="/concepts/system-prompt" icon="message-lines">
111-
How `SOUL.md` is composed into the per-turn system prompt.
111+
How `SOUL.md` is composed into OpenClaw and Codex runtime context.
112112
</Card>
113113
<Card title="SOUL.md template" href="/reference/templates/SOUL" icon="file-lines">
114114
Starter template for a personality file.

‎docs/concepts/system-prompt.md‎

Lines changed: 15 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -166,7 +166,8 @@ PR.
166166

167167
## Workspace bootstrap injection
168168

169-
Bootstrap files are trimmed and appended under **Project Context** so the model sees identity and profile context without needing explicit reads:
169+
Bootstrap files are resolved from the active workspace, then routed to the
170+
prompt surface that matches their lifetime:
170171

171172
- `AGENTS.md`
172173
- `SOUL.md`
@@ -177,23 +178,24 @@ Bootstrap files are trimmed and appended under **Project Context** so the model
177178
- `BOOTSTRAP.md` (only on brand-new workspaces)
178179
- `MEMORY.md` when present
179180

180-
All of these files are **injected into the context window** on every turn unless
181-
a file-specific gate applies. `HEARTBEAT.md` is omitted on normal runs when
182-
heartbeats are disabled for the default agent or
181+
On the native Codex harness, OpenClaw avoids repeating stable workspace files
182+
in every user turn. Codex loads `AGENTS.md` through its own project-doc
183+
discovery. `SOUL.md`, `IDENTITY.md`, `TOOLS.md`, and `USER.md` are forwarded as
184+
Codex developer instructions. `HEARTBEAT.md` content is not injected; heartbeat
185+
turns get a collaboration-mode note pointing to the file when it exists and is
186+
non-empty. `MEMORY.md` and active `BOOTSTRAP.md` content keep the normal
187+
turn-context role for now.
188+
189+
On non-Codex harnesses, bootstrap files continue to be composed into the
190+
OpenClaw prompt according to their existing gates. `HEARTBEAT.md` is omitted on
191+
normal runs when heartbeats are disabled for the default agent or
183192
`agents.defaults.heartbeat.includeSystemPromptSection` is false. Keep injected
184-
files concise, especially `MEMORY.md`. `MEMORY.md` is intended to stay a
185-
curated long-term summary; detailed daily notes belong in `memory/*.md` where
193+
files concise, especially `MEMORY.md`. `MEMORY.md` is intended to stay a curated
194+
long-term summary; detailed daily notes belong in `memory/*.md` where
186195
`memory_search` and `memory_get` can retrieve them on demand. Oversized
187196
`MEMORY.md` files increase prompt usage and can be partially injected because of
188197
the bootstrap file limits below.
189198

190-
When a session runs on the native Codex harness, Codex loads `AGENTS.md`
191-
through its own project-doc discovery. OpenClaw still resolves the remaining
192-
bootstrap files and forwards them as Codex config instructions, so `SOUL.md`,
193-
`TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`, and
194-
`MEMORY.md` keep the same workspace-context role without duplicating
195-
`AGENTS.md`.
196-
197199
<Note>
198200
`memory/*.md` daily files are **not** part of the normal bootstrap Project Context. On ordinary turns they are accessed on demand via the `memory_search` and `memory_get` tools, so they do not count against the context window unless the model explicitly reads them. Bare `/new` and `/reset` turns are the exception: the runtime can prepend recent daily memory as a one-shot startup-context block for that first turn.
199201
</Note>

‎docs/gateway/heartbeat.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -376,10 +376,12 @@ channels:
376376

377377
## HEARTBEAT.md (optional)
378378

379-
If a `HEARTBEAT.md` file exists in the workspace, the default prompt tells the agent to read it. Think of it as your "heartbeat checklist": small, stable, and safe to include every 30 minutes.
379+
If a `HEARTBEAT.md` file exists in the workspace, the default prompt tells the agent to read it. Think of it as your "heartbeat checklist": small, stable, and safe to consider every 30 minutes.
380380

381381
On normal runs, `HEARTBEAT.md` is only injected when heartbeat guidance is enabled for the default agent. Disabling the heartbeat cadence with `0m` or setting `includeSystemPromptSection: false` omits it from normal bootstrap context.
382382

383+
On the native Codex harness, `HEARTBEAT.md` content is not injected into the turn. If the file exists and has non-whitespace content, the heartbeat collaboration-mode instructions point Codex at the file and tell it to read before proceeding.
384+
383385
If `HEARTBEAT.md` exists but is effectively empty (only blank lines and markdown headers like `# Heading`), OpenClaw skips the heartbeat run to save API calls. That skip is reported as `reason=empty-heartbeat-file`. If the file is missing, the heartbeat still runs and the model decides what to do.
384386

385387
Keep it tiny (short checklist or reminders) to avoid prompt bloat.

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

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -361,11 +361,12 @@ filenames for persona files, because Codex fallbacks only apply when
361361
`AGENTS.md` is missing.
362362

363363
For OpenClaw workspace parity, the Codex harness resolves the other bootstrap
364-
files, including `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`,
365-
`HEARTBEAT.md`, `BOOTSTRAP.md`, and `MEMORY.md` when present, and forwards them
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`.
364+
files. `SOUL.md`, `IDENTITY.md`, `TOOLS.md`, and `USER.md` are forwarded as
365+
OpenClaw Codex developer instructions because they define the active agent,
366+
available workspace guidance, and user profile. `HEARTBEAT.md` content is not
367+
injected; heartbeat turns get a collaboration-mode pointer to read the file when
368+
it exists and is non-empty. `BOOTSTRAP.md` and `MEMORY.md` when present are
369+
forwarded as OpenClaw turn input reference context.
369370

370371
## Environment overrides
371372

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

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -31,11 +31,11 @@ when it uses Codex-flavored OpenAI auth or transport.
3131
Native Codex keeps Codex-owned base/model/personality instructions and
3232
project-doc behavior according to the active Codex thread config. Lightweight
3333
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.
34+
developer instructions cover OpenClaw runtime concerns such as source-channel
35+
delivery, OpenClaw dynamic tools, ACP delegation, adapter context, and the
36+
active agent workspace profile files. OpenClaw skill catalogs plus `MEMORY.md`
37+
and active `BOOTSTRAP.md` content are projected as turn input reference context
38+
for native Codex.
3939

4040
## Thread bindings and model changes
4141

@@ -61,7 +61,9 @@ quiet or notify without encoding that control flow in final text.
6161
Heartbeat-specific initiative guidance is sent as a Codex collaboration-mode
6262
developer instruction on the heartbeat turn itself. Ordinary chat turns restore
6363
Codex Default mode instead of carrying heartbeat philosophy in their normal
64-
runtime prompt.
64+
runtime prompt. When a non-empty `HEARTBEAT.md` exists, the heartbeat
65+
collaboration-mode instructions point Codex at the file instead of inlining its
66+
contents.
6567

6668
## Hook boundaries
6769

0 commit comments

Comments
 (0)