Skip to content

Commit e4b4486

Browse files
gumadeirasgumadeiras
authored
Agent: unify bootstrap truncation warning handling (#32769)
Merged via squash. Prepared head SHA: 5d6d4dd Co-authored-by: gumadeiras <[email protected]> Co-authored-by: gumadeiras <[email protected]> Reviewed-by: @gumadeiras
1 parent 3ad3a90 commit e4b4486

34 files changed

+1485
-221
lines changed

‎docs/concepts/context.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -114,6 +114,8 @@ By default, OpenClaw injects a fixed set of workspace files (if present):
114114

115115
Large files are truncated per-file using `agents.defaults.bootstrapMaxChars` (default `20000` chars). OpenClaw also enforces a total bootstrap injection cap across files with `agents.defaults.bootstrapTotalMaxChars` (default `150000` chars). `/context` shows **raw vs injected** sizes and whether truncation happened.
116116

117+
When truncation occurs, the runtime can inject an in-prompt warning block under Project Context. Configure this with `agents.defaults.bootstrapPromptTruncationWarning` (`off`, `once`, `always`; default `once`).
118+
117119
## Skills: what’s injected vs loaded on-demand
118120

119121
The system prompt includes a compact **skills list** (name + description + location). This list has real overhead.

‎docs/concepts/system-prompt.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -73,7 +73,10 @@ compaction.
7373
Large files are truncated with a marker. The max per-file size is controlled by
7474
`agents.defaults.bootstrapMaxChars` (default: 20000). Total injected bootstrap
7575
content across files is capped by `agents.defaults.bootstrapTotalMaxChars`
76-
(default: 150000). Missing files inject a short missing-file marker.
76+
(default: 150000). Missing files inject a short missing-file marker. When truncation
77+
occurs, OpenClaw can inject a warning block in Project Context; control this with
78+
`agents.defaults.bootstrapPromptTruncationWarning` (`off`, `once`, `always`;
79+
default: `once`).
7780

7881
Sub-agent sessions only inject `AGENTS.md` and `TOOLS.md` (other bootstrap files
7982
are filtered out to keep the sub-agent context small).

‎docs/gateway/configuration-reference.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -801,6 +801,21 @@ Max total characters injected across all workspace bootstrap files. Default: `15
801801
}
802802
```
803803

804+
### `agents.defaults.bootstrapPromptTruncationWarning`
805+
806+
Controls agent-visible warning text when bootstrap context is truncated.
807+
Default: `"once"`.
808+
809+
- `"off"`: never inject warning text into the system prompt.
810+
- `"once"`: inject warning once per unique truncation signature (recommended).
811+
- `"always"`: inject warning on every run when truncation exists.
812+
813+
```json5
814+
{
815+
agents: { defaults: { bootstrapPromptTruncationWarning: "once" } }, // off | once | always
816+
}
817+
```
818+
804819
### `agents.defaults.imageMaxDimensionPx`
805820

806821
Max pixel size for the longest image side in transcript/tool image blocks before provider calls.

0 commit comments

Comments
 (0)