From a136cafe983b99c96561d5dc2d00dfa78d80ac1a Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Sat, 16 May 2026 15:46:44 -0700 Subject: [PATCH] Default bootstrap truncation warnings to always (#81918) * Default bootstrap truncation warnings to always Make bootstrap truncation warnings surface on every affected run by default while preserving explicit off and once configuration. * Refresh checks after proof formatting fix * Refresh checks after live proof update * docs: align bootstrap warning default reference Update the public agent config reference to match the new default bootstrapPromptTruncationWarning mode and recommended example. --- docs/concepts/context.md | 2 +- docs/concepts/system-prompt.md | 2 +- docs/gateway/config-agents.md | 8 ++++---- ...bedded-helpers.buildbootstrapcontextfiles.test.ts | 12 ++++++++---- src/agents/pi-embedded-helpers/bootstrap.ts | 2 +- src/config/schema.help.ts | 2 +- src/config/types.agent-defaults.ts | 4 ++-- 7 files changed, 18 insertions(+), 14 deletions(-) diff --git a/docs/concepts/context.md b/docs/concepts/context.md index 50e42714ebb..9952a52b29f 100644 --- a/docs/concepts/context.md +++ b/docs/concepts/context.md @@ -124,7 +124,7 @@ By default, OpenClaw injects a fixed set of workspace files (if present): Large files are truncated per-file using `agents.defaults.bootstrapMaxChars` (default `12000` chars). OpenClaw also enforces a total bootstrap injection cap across files with `agents.defaults.bootstrapTotalMaxChars` (default `60000` chars). `/context` shows **raw vs injected** sizes and whether truncation happened. -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`). +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 `always`). ## Skills: injected vs loaded on-demand diff --git a/docs/concepts/system-prompt.md b/docs/concepts/system-prompt.md index 7f89f7321f2..cdb965e255a 100644 --- a/docs/concepts/system-prompt.md +++ b/docs/concepts/system-prompt.md @@ -204,7 +204,7 @@ content across files is capped by `agents.defaults.bootstrapTotalMaxChars` (default: 60000). Missing files inject a short missing-file marker. When truncation occurs, OpenClaw can inject a concise system-prompt warning notice; control this with `agents.defaults.bootstrapPromptTruncationWarning` (`off`, `once`, `always`; -default: `once`). Detailed raw/injected counts stay in diagnostics such as +default: `always`). Detailed raw/injected counts stay in diagnostics such as `/context`, `/status`, doctor, and logs. For memory files, truncation is not data loss: the file remains intact on disk, diff --git a/docs/gateway/config-agents.md b/docs/gateway/config-agents.md index 040d9a4f537..394ea6dc208 100644 --- a/docs/gateway/config-agents.md +++ b/docs/gateway/config-agents.md @@ -156,11 +156,11 @@ injection behavior from the shared defaults. Omitted fields inherit from ### `agents.defaults.bootstrapPromptTruncationWarning` Controls the agent-visible system-prompt notice when bootstrap context is truncated. -Default: `"once"`. +Default: `"always"`. - `"off"`: never inject truncation notice text into the system prompt. -- `"once"`: inject a concise notice once per unique truncation signature (recommended). -- `"always"`: inject a concise notice on every run when truncation exists. +- `"once"`: inject a concise notice once per unique truncation signature. +- `"always"`: inject a concise notice on every run when truncation exists (recommended). Detailed raw/injected counts and config tuning fields stay in diagnostics such as context/status reports and logs; routine WebChat user/runtime context only @@ -168,7 +168,7 @@ gets the concise recovery notice. ```json5 { - agents: { defaults: { bootstrapPromptTruncationWarning: "once" } }, // off | once | always + agents: { defaults: { bootstrapPromptTruncationWarning: "always" } }, // off | once | always } ``` diff --git a/src/agents/pi-embedded-helpers.buildbootstrapcontextfiles.test.ts b/src/agents/pi-embedded-helpers.buildbootstrapcontextfiles.test.ts index 06f2667b33f..2fed744a37d 100644 --- a/src/agents/pi-embedded-helpers.buildbootstrapcontextfiles.test.ts +++ b/src/agents/pi-embedded-helpers.buildbootstrapcontextfiles.test.ts @@ -293,10 +293,9 @@ describe("bootstrap limit resolvers", () => { }); describe("resolveBootstrapPromptTruncationWarningMode", () => { - it("defaults to once", () => { - expect(resolveBootstrapPromptTruncationWarningMode()).toBe( - DEFAULT_BOOTSTRAP_PROMPT_TRUNCATION_WARNING_MODE, - ); + it("defaults to always", () => { + expect(resolveBootstrapPromptTruncationWarningMode()).toBe("always"); + expect(DEFAULT_BOOTSTRAP_PROMPT_TRUNCATION_WARNING_MODE).toBe("always"); }); it("accepts explicit valid modes", () => { @@ -305,6 +304,11 @@ describe("resolveBootstrapPromptTruncationWarningMode", () => { agents: { defaults: { bootstrapPromptTruncationWarning: "off" } }, } as OpenClawConfig), ).toBe("off"); + expect( + resolveBootstrapPromptTruncationWarningMode({ + agents: { defaults: { bootstrapPromptTruncationWarning: "once" } }, + } as OpenClawConfig), + ).toBe("once"); expect( resolveBootstrapPromptTruncationWarningMode({ agents: { defaults: { bootstrapPromptTruncationWarning: "always" } }, diff --git a/src/agents/pi-embedded-helpers/bootstrap.ts b/src/agents/pi-embedded-helpers/bootstrap.ts index 6b08d62ebf0..644fbc0bef7 100644 --- a/src/agents/pi-embedded-helpers/bootstrap.ts +++ b/src/agents/pi-embedded-helpers/bootstrap.ts @@ -87,7 +87,7 @@ export function stripThoughtSignatures( export const DEFAULT_BOOTSTRAP_MAX_CHARS = 12_000; export const DEFAULT_BOOTSTRAP_TOTAL_MAX_CHARS = 60_000; -export const DEFAULT_BOOTSTRAP_PROMPT_TRUNCATION_WARNING_MODE = "once"; +export const DEFAULT_BOOTSTRAP_PROMPT_TRUNCATION_WARNING_MODE = "always"; const MIN_BOOTSTRAP_FILE_BUDGET_CHARS = 64; // Ratios split `contentBudget` (= maxChars − marker.length − join separators), not `maxChars`. // The marker and "\n" separators are already reserved before this split runs; these ratios diff --git a/src/config/schema.help.ts b/src/config/schema.help.ts index 0e1c616356a..8d478d1e312 100644 --- a/src/config/schema.help.ts +++ b/src/config/schema.help.ts @@ -1079,7 +1079,7 @@ export const FIELD_HELP: Record = { "agents.defaults.experimental.localModelLean": "Experimental local-model prompt trim. When enabled, OpenClaw drops heavyweight default tools like browser, cron, and message for weaker or smaller local-model backends.", "agents.defaults.bootstrapPromptTruncationWarning": - 'Inject agent-visible warning text when bootstrap files are truncated: "off", "once" (default), or "always".', + 'Inject agent-visible warning text when bootstrap files are truncated: "off", "once", or "always" (default).', "agents.defaults.startupContext": 'Runtime-owned first-turn prelude for bare "/new" and "/reset". Use this to control whether recent daily memory files are preloaded into the first prompt instead of asking the model to decide what to read.', "agents.defaults.startupContext.enabled": diff --git a/src/config/types.agent-defaults.ts b/src/config/types.agent-defaults.ts index d10158de1c7..ffcdaf64213 100644 --- a/src/config/types.agent-defaults.ts +++ b/src/config/types.agent-defaults.ts @@ -273,8 +273,8 @@ export type AgentDefaultsConfig = { /** * Agent-visible bootstrap truncation warning mode: * - off: do not inject warning text - * - once: inject once per unique truncation signature (default) - * - always: inject on every run with truncation + * - once: inject once per unique truncation signature + * - always: inject on every run with truncation (default) */ bootstrapPromptTruncationWarning?: "off" | "once" | "always"; /** Optional IANA timezone for the user (used in system prompt; defaults to host timezone). */