fix(agents): honor skipBootstrap at runtime injection path (#75184) by lonexreb · Pull Request #75217 · openclaw/openclaw

lonexreb · 2026-04-30T18:56:49Z

Summary

Problem: agents.defaults.skipBootstrap: true was advertised as a way to skip workspace bootstrap content, but it was a no-op for the runtime system-prompt injection. systemPromptReport still showed AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, BOOTSTRAP.md injected with their full per-file content.
Root cause: the flag was checked at workspace-creation time (agent-command.ts:375 -> ensureBootstrapFiles: !agentCfg?.skipBootstrap) but the runtime injection path resolveBootstrapFilesForRun (and resolveBootstrapContextForRun which wraps it) loaded the workspace bootstrap files unconditionally. So files created during a previous bootstrap kept being injected even after the operator set the flag.
What changed: added an early return in resolveBootstrapFilesForRun when config.agents.defaults.skipBootstrap === true. Empty bootstrap files → empty contextFiles → no injection. Workspace-creation behavior unchanged.

Linked Issue

Test Plan

pnpm tsgo:core clean
pnpm exec oxfmt --check clean

Real behavior proof

Test: pnpm test src/agents/bootstrap-files.test.ts — 30 passed.

The new test registers an agent:bootstrap hook, sets agents.defaults.skipBootstrap: true, and asserts the hook-injected EXTRA.md reaches the resolver output even though workspace AGENTS.md is suppressed. This exercises the same production code path that runs every gateway turn — resolveBootstrapFilesForRun → applyBootstrapHookOverrides — without mocking the hook runner.

clawsweeper · 2026-04-30T19:00:21Z

Codex review: needs real behavior proof before merge.

Summary
The PR updates bootstrap-file resolution, config docs/JSDoc, and resolver tests so agents.defaults.skipBootstrap suppresses existing workspace bootstrap files at runtime while preserving hook-injected context.

Reproducibility: yes. for source-level reproduction: current main loads workspace bootstrap files in resolveBootstrapFilesForRun without consulting skipBootstrap, while workspace creation already honors the flag. I did not establish a live current-main failing agent turn in this read-only review.

Real behavior proof
Needs real behavior proof before merge: The PR body provides tests and checks only; it does not include after-fix output from a real OpenClaw run showing the changed systemPromptReport.

Next step before merge
External contributor real behavior proof is missing, so the next action is contributor/maintainer review rather than an automated repair lane.

Security
Cleared: The diff is limited to agent bootstrap filtering, docs/JSDoc, and tests, with no dependency, CI, permission, secret-handling, or downloaded-code changes.

Review findings

[P2] Sync skipBootstrap schema metadata — src/config/types.agent-defaults.ts:233-241
[P3] Add the required changelog entry — docs/gateway/config-agents.md:62-67

Review details

Best possible solution:

Land the resolver-level workspace-file skip with hook preservation after adding schema/help/label/generated metadata, a changelog Fixes entry, and real openclaw agent --json proof showing workspace bootstrap files are absent from systemPromptReport under skipBootstrap: true.

Do we have a high-confidence way to reproduce the issue?

Yes for source-level reproduction: current main loads workspace bootstrap files in resolveBootstrapFilesForRun without consulting skipBootstrap, while workspace creation already honors the flag. I did not establish a live current-main failing agent turn in this read-only review.

Is this the best way to solve the issue?

No, not yet. The resolver-level boundary and hook-preserving approach are the right maintainable direction, but schema metadata, changelog, and real behavior proof still need to be completed before merge.

Full review comments:

[P2] Sync skipBootstrap schema metadata — src/config/types.agent-defaults.ts:233-241
The docs/JSDoc now promise runtime-injection semantics, but openclaw config schema is built from schema help/labels and the generated baseline, which this PR does not update. CLI and Control UI schema lookup would still show skipBootstrap as a bare boolean with no scope hint, so add the label/help metadata and regenerate src/config/schema.base.generated.ts.
Confidence: 0.9
[P3] Add the required changelog entry — docs/gateway/config-agents.md:62-67
This is a user-facing agents config/runtime fix, but the PR leaves CHANGELOG.md untouched. Add a single-line Fixes entry under the active release section before merge.
Confidence: 0.9

Overall correctness: patch is incorrect
Overall confidence: 0.9

What I checked:

Current main source reproduction: resolveBootstrapFilesForRun loads workspace bootstrap files before hook overrides without checking agents.defaults.skipBootstrap, so existing AGENTS.md/SOUL.md files can still enter runtime prompt assembly. (src/agents/bootstrap-files.ts:241, 7d5ca3064a51)
Creation path already honors skipBootstrap: Workspace setup already passes ensureBootstrapFiles: !agentCfg?.skipBootstrap, narrowing the bug to runtime injection rather than initial file creation. (src/agents/agent-command.ts:392, 7d5ca3064a51)
PR head verified: The pull request head still resolves to b466f60, matching the provided review context. (b466f6065e0b)
PR implementation shape: The PR suppresses workspace file loading when skipBootstrap is true while still feeding an empty file list through applyBootstrapHookOverrides, so hook-injected bootstrap context can survive. (src/agents/bootstrap-files.ts:245, b466f6065e0b)
Regression coverage added: The PR adds resolver tests for pre-existing workspace files under skipBootstrap: true, the default path, and hook-injected EXTRA.md surviving with workspace AGENTS.md suppressed. (src/agents/bootstrap-files.test.ts:146, b466f6065e0b)
Config schema metadata still missing: The generated runtime schema still exposes agents.defaults.skipBootstrap as a bare boolean, and nearby schema help/labels do not include a skipBootstrap entry. (src/config/schema.base.generated.ts:3754, 7d5ca3064a51)

Likely related people:

steipete: Prior ClawSweeper context for this PR identified recent maintenance around bootstrap resolver, cache behavior, heartbeat controls, and prompt assembly; the affected path is in that agent runtime area. (role: adjacent maintainer; confidence: medium; files: src/agents/bootstrap-files.ts, src/agents/pi-embedded-runner/run/attempt.ts, src/agents/cli-runner/prepare.ts)
Shakker: Local blame in this checkout attributes the current resolver and generated schema/help/label files to the grafted current-main snapshot commit, so this is a weak but relevant current-tree routing signal. (role: recent maintainer; confidence: low; commits: 9b0afd81413a; files: src/agents/bootstrap-files.ts, src/config/schema.base.generated.ts, src/config/schema.help.ts)

Remaining risk / open question:

External contributor real behavior proof is still absent, so the PR should not merge under the current proof gate.
The Control UI/CLI config schema surface would still omit the updated skipBootstrap contract unless schema labels/help and generated baseline are updated.
The user-facing fix still lacks the required changelog entry.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 7d5ca3064a51.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a69ba75e9d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-04-30T19:00:33Z

+  if (params.config?.agents?.defaults?.skipBootstrap === true) {
+    return [];
+  }


Keep bootstrap hooks active when skipBootstrap is enabled

This early return bypasses applyBootstrapHookOverrides, so agent:bootstrap hooks never run when agents.defaults.skipBootstrap is true. That is a behavior regression for setups that skip default workspace bootstrap files but still rely on hook-provided context (for example the bundled bootstrap-extra-files handler in src/hooks/bundled/bootstrap-extra-files/handler.ts:25), because those injected files now disappear from runtime prompt assembly.

Useful? React with 👍 / 👎.

…for existing workspace files Codex review on PR openclaw#75217 noted that the runtime resolver guard correctly honors agents.defaults.skipBootstrap, but the public docs at docs/gateway/config-agents.md still described it as workspace-creation-only, and the diff did not include a regression proving `contextFiles` / `injectedWorkspaceFiles` stay empty when existing workspace files are present and skipBootstrap is true. Align the public contract with the new runtime behavior: - docs/gateway/config-agents.md now describes both effects of skipBootstrap (creation + runtime injection) and points users at `contextInjection: 'never'` if they want to keep files on disk but skip injection only. - src/config/types.agent-defaults.ts JSDoc on `skipBootstrap` mirrors the doc wording so editor hover and SDK consumers see the same contract. Add a regression in src/agents/bootstrap-files.test.ts that exercises the exact failure mode the issue described: write AGENTS.md and SOUL.md into the workspace, then call resolveBootstrapFilesForRun and resolveBootstrapContextForRun with skipBootstrap=true and assert both return empty results. A second case sets skipBootstrap=false / unset and asserts AGENTS.md is still resolved, so the guard does not regress the default path. Refs openclaw#75184

lonexreb · 2026-04-30T20:54:04Z

Round-1 review addressed in 4dcbde0.

The bot was right that the public config contract had drifted from the new runtime behavior, and that the diff lacked a regression for the existing-workspace-files case.

Changes:

docs/gateway/config-agents.md — agents.defaults.skipBootstrap is now documented as having two effects (creation + runtime injection), with a callout pointing users at contextInjection: "never" if they want to keep files on disk but skip injection only.
src/config/types.agent-defaults.ts — JSDoc on skipBootstrap mirrors the doc wording so editor hover and SDK consumers see the same contract.
src/agents/bootstrap-files.test.ts — added two regression cases:
- With agents.defaults.skipBootstrap: true and pre-existing AGENTS.md + SOUL.md on disk: both resolveBootstrapFilesForRun and resolveBootstrapContextForRun return empty (contextFiles: []).
- With skipBootstrap: false / unset and pre-existing AGENTS.md: the file still resolves, so the guard does not regress the default path.

Acceptance criteria checked locally:

pnpm test src/agents/bootstrap-files.test.ts — 29/29 pass
pnpm tsgo:core — clean
pnpm exec oxfmt --check --threads=1 docs/gateway/config-agents.md src/agents/bootstrap-files.test.ts src/config/types.agent-defaults.ts — clean

PTAL.

…for existing workspace files Codex review on PR openclaw#75217 noted that the runtime resolver guard correctly honors agents.defaults.skipBootstrap, but the public docs at docs/gateway/config-agents.md still described it as workspace-creation-only, and the diff did not include a regression proving `contextFiles` / `injectedWorkspaceFiles` stay empty when existing workspace files are present and skipBootstrap is true. Align the public contract with the new runtime behavior: - docs/gateway/config-agents.md now describes both effects of skipBootstrap (creation + runtime injection) and points users at `contextInjection: 'never'` if they want to keep files on disk but skip injection only. - src/config/types.agent-defaults.ts JSDoc on `skipBootstrap` mirrors the doc wording so editor hover and SDK consumers see the same contract. Add a regression in src/agents/bootstrap-files.test.ts that exercises the exact failure mode the issue described: write AGENTS.md and SOUL.md into the workspace, then call resolveBootstrapFilesForRun and resolveBootstrapContextForRun with skipBootstrap=true and assert both return empty results. A second case sets skipBootstrap=false / unset and asserts AGENTS.md is still resolved, so the guard does not regress the default path. Refs openclaw#75184

lonexreb · 2026-05-05T04:43:30Z

Addressed [P2] from codex review (src/agents/bootstrap-files.ts:245). The early return when skipBootstrap was true bypassed applyBootstrapHookOverrides, breaking installations that opt out of default workspace files but rely on hook-injected context (e.g. the bundled bootstrap-extra-files handler). Reworked the path so skipBootstrap only suppresses the WORKSPACE file load — hooks still run against an empty file list and their injected files survive into prompt assembly. Added a regression test that registers an agent:bootstrap hook, sets skipBootstrap: true, and asserts the hook-injected EXTRA.md still appears even though workspace AGENTS.md is suppressed. 30 tests pass. Also rebased onto current origin/main.

Re-review progress:

State: Complete
Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
Run: https://github.com/openclaw/clawsweeper/actions/runs/25395439858
Updated: 2026-05-05T18:49:37.651Z

…for existing workspace files Codex review on PR openclaw#75217 noted that the runtime resolver guard correctly honors agents.defaults.skipBootstrap, but the public docs at docs/gateway/config-agents.md still described it as workspace-creation-only, and the diff did not include a regression proving `contextFiles` / `injectedWorkspaceFiles` stay empty when existing workspace files are present and skipBootstrap is true. Align the public contract with the new runtime behavior: - docs/gateway/config-agents.md now describes both effects of skipBootstrap (creation + runtime injection) and points users at `contextInjection: 'never'` if they want to keep files on disk but skip injection only. - src/config/types.agent-defaults.ts JSDoc on `skipBootstrap` mirrors the doc wording so editor hover and SDK consumers see the same contract. Add a regression in src/agents/bootstrap-files.test.ts that exercises the exact failure mode the issue described: write AGENTS.md and SOUL.md into the workspace, then call resolveBootstrapFilesForRun and resolveBootstrapContextForRun with skipBootstrap=true and assert both return empty results. A second case sets skipBootstrap=false / unset and asserts AGENTS.md is still resolved, so the guard does not regress the default path. Refs openclaw#75184

…enabled Codex follow-up on PR openclaw#75217 noted: the early return when agents.defaults.skipBootstrap was true bypassed applyBootstrapHookOverrides entirely, so agent:bootstrap hooks (e.g. the bundled bootstrap-extra-files handler in src/hooks/bundled/bootstrap-extra-files/handler.ts) never ran when the flag was set. That broke installations that opt out of default workspace bootstrap files but still rely on hook-injected context. skipBootstrap is meant to suppress only the WORKSPACE bootstrap files — hooks should still run. Skip the workspace file load when the flag is set and feed an empty file list into applyBootstrapHookOverrides; hooks can then return their own files which we sanitize and return like any other bootstrap result. Add a regression test that registers an agent:bootstrap hook, sets skipBootstrap to true, and asserts the hook-injected EXTRA.md still appears even though workspace AGENTS.md is suppressed.

…75184) agents.defaults.skipBootstrap was checked at workspace-creation time (agent-command.ts:375 -> ensureBootstrapFiles) but the runtime injection path resolveBootstrapFilesForRun loaded and injected the workspace bootstrap files (AGENTS.md, SOUL.md, TOOLS.md, etc.) unconditionally. Result: setting skipBootstrap: true was a no-op for the system prompt — the systemPromptReport still showed all bootstrap files injected with their full per-file content. Add an early return in resolveBootstrapFilesForRun when config.agents.defaults.skipBootstrap is true, so configured opt-outs also stop the injection path. Workspace creation behavior is unchanged (the existing ensureBootstrapFiles guard still fires). Closes openclaw#75184

…for existing workspace files Codex review on PR openclaw#75217 noted that the runtime resolver guard correctly honors agents.defaults.skipBootstrap, but the public docs at docs/gateway/config-agents.md still described it as workspace-creation-only, and the diff did not include a regression proving `contextFiles` / `injectedWorkspaceFiles` stay empty when existing workspace files are present and skipBootstrap is true. Align the public contract with the new runtime behavior: - docs/gateway/config-agents.md now describes both effects of skipBootstrap (creation + runtime injection) and points users at `contextInjection: 'never'` if they want to keep files on disk but skip injection only. - src/config/types.agent-defaults.ts JSDoc on `skipBootstrap` mirrors the doc wording so editor hover and SDK consumers see the same contract. Add a regression in src/agents/bootstrap-files.test.ts that exercises the exact failure mode the issue described: write AGENTS.md and SOUL.md into the workspace, then call resolveBootstrapFilesForRun and resolveBootstrapContextForRun with skipBootstrap=true and assert both return empty results. A second case sets skipBootstrap=false / unset and asserts AGENTS.md is still resolved, so the guard does not regress the default path. Refs openclaw#75184

…enabled Codex follow-up on PR openclaw#75217 noted: the early return when agents.defaults.skipBootstrap was true bypassed applyBootstrapHookOverrides entirely, so agent:bootstrap hooks (e.g. the bundled bootstrap-extra-files handler in src/hooks/bundled/bootstrap-extra-files/handler.ts) never ran when the flag was set. That broke installations that opt out of default workspace bootstrap files but still rely on hook-injected context. skipBootstrap is meant to suppress only the WORKSPACE bootstrap files — hooks should still run. Skip the workspace file load when the flag is set and feed an empty file list into applyBootstrapHookOverrides; hooks can then return their own files which we sanitize and return like any other bootstrap result. Add a regression test that registers an agent:bootstrap hook, sets skipBootstrap to true, and asserts the hook-injected EXTRA.md still appears even though workspace AGENTS.md is suppressed.

…ype portability CI check-test-types flagged the new regression test for comparing WorkspaceBootstrapFile.name (a typed union of canonical bootstrap names) against the literal 'EXTRA.md' which is not in the union. Hooks are allowed to inject arbitrary file names, so compare via String() to keep the assertion type-portable without binding the test to the union shape.

Lint flagged String(file.name) as 'type conversion does not change the type or value'. Widen via .map((f) => f.name): string[] for the .includes check, and use file.name as string for the .find predicate.

martingarramon

The short-circuit before the workspace load while keeping applyBootstrapHookOverrides in the path is the right fix for the codex-bot follow-up about hook bypass, and the second test (hook-injected EXTRA.md survives skipBootstrap: true) locks that contract concretely.

One Q + a nit:

Q: bootstrapFilesToSkip interaction. When both skipBootstrap: true and bootstrapFilesToSkip: ["AGENTS.md"] are set, bootstrapFilesToSkip is ignored — skipBootstrap short-circuits the workspace load at src/agents/bootstrap-files.ts:248 before bootstrapFilesToSkip is evaluated. The behavior is internally consistent, but the AgentDefaultsConfig JSDoc and the docs page don't mention this layering. Please add a one-liner so users who set both knobs aren't surprised that their selective skiplist is silently ignored.

Nit: test comment at src/agents/bootstrap-files.test.ts:148 cites agent-command.ts:373 for ensureBootstrapFiles: !skipBootstrap. This line number is already stale — agent-command.ts:392 on current upstream/main. Either drop the line number or pin via a symbol-name reference.

LGTM otherwise.

openclaw-barnacle Bot added agents Agent runtime and tooling size: XS labels Apr 30, 2026

chatgpt-codex-connector Bot reviewed Apr 30, 2026

View reviewed changes

openclaw-barnacle Bot added docs Improvements or additions to documentation gateway Gateway runtime labels Apr 30, 2026

openclaw-barnacle Bot added size: S and removed size: XS labels Apr 30, 2026

clawsweeper Bot mentioned this pull request May 1, 2026

[Bug]: agents.defaults.skipBootstrap: true is a no-op for workspace bootstrap files #75184

Open

lonexreb force-pushed the fix/75184-skip-bootstrap-honor-flag branch from 4dcbde0 to 25ee550 Compare May 3, 2026 08:09

lonexreb force-pushed the fix/75184-skip-bootstrap-honor-flag branch from 25ee550 to 3384452 Compare May 5, 2026 04:43

openclaw-barnacle Bot added the triage: needs-real-behavior-proof Candidate: external PR needs after-fix proof from a real setup. label May 5, 2026

lonexreb added 4 commits May 5, 2026 00:26

lonexreb force-pushed the fix/75184-skip-bootstrap-honor-flag branch from 230d7a3 to c9774b1 Compare May 5, 2026 05:26

fix(agents): widen file.name to string before comparison to satisfy lint

b466f60

Lint flagged String(file.name) as 'type conversion does not change the type or value'. Widen via .map((f) => f.name): string[] for the .includes check, and use file.name as string for the .find predicate.

martingarramon reviewed May 6, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix(agents): honor skipBootstrap at runtime injection path (#75184)#75217

fix(agents): honor skipBootstrap at runtime injection path (#75184)#75217
lonexreb wants to merge 5 commits intoopenclaw:mainfrom
lonexreb:fix/75184-skip-bootstrap-honor-flag

lonexreb commented Apr 30, 2026 •

edited

Loading

Uh oh!

clawsweeper Bot commented Apr 30, 2026 •

edited

Loading

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot Apr 30, 2026

Uh oh!

lonexreb commented Apr 30, 2026

Uh oh!

lonexreb commented May 5, 2026 •

edited by clawsweeper Bot

Loading

Uh oh!

martingarramon left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

lonexreb commented Apr 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Linked Issue

Test Plan

Real behavior proof

Uh oh!

clawsweeper Bot commented Apr 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Apr 30, 2026

Choose a reason for hiding this comment

Uh oh!

lonexreb commented Apr 30, 2026

Uh oh!

lonexreb commented May 5, 2026 • edited by clawsweeper Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

martingarramon left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

lonexreb commented Apr 30, 2026 •

edited

Loading

clawsweeper Bot commented Apr 30, 2026 •

edited

Loading

lonexreb commented May 5, 2026 •

edited by clawsweeper Bot

Loading