fix: add self-knowledge docs rule to system prompt by SutraHsing · Pull Request #90882 · openclaw/openclaw

SutraHsing · 2026-06-06T08:36:11Z

Summary

Refines the generated Documentation self-knowledge rule so docs are authoritative before the model understands how OpenClaw works.
Keeps the docs-first behavior strong for memory/daily notes, sessions, tools, Gateway, config, commands, and project context.
Clarifies that AGENTS.md, project/workspace/profile/memory context, and memory_search are instruction context or user memory, not OpenClaw design/implementation knowledge.
Covers local docs, public docs, read-tool casing, and concise wording in src/agents/system-prompt.test.ts.
Updates docs/concepts/system-prompt.md so the docs match the generated prompt behavior.

Fixes #90713.
Addresses the review direction from #90719.

Verification

pnpm docs:list
pnpm test src/agents/system-prompt.test.ts
pnpm test src/agents/system-prompt.test.ts src/agents/cli-runner/prepare.test.ts src/agents/cli-runner/helpers.system-prompt.test.ts
pnpm exec oxfmt --check --threads=1 src/agents/system-prompt.ts src/agents/system-prompt.test.ts src/agents/cli-runner/prepare.test.ts
node scripts/format-docs.mjs --check docs/concepts/system-prompt.md
git diff --check
pnpm build
Live isolated agent run with zai/glm-5.1

Prompt size

Using OpenClaw's normal-text precheck estimate, ceil(chars / 4):

Documentation section	Chars	Approx tokens
Before PR/main	449	113
Earlier verbose version	1220	305
Prior strong concise version	701	176
Final wording in this PR	778	195

Compared with the earlier verbose version, the final wording saves about 442 chars / 111 tokens. Compared with main, the net addition is about 329 chars / 83 tokens. Compared with the prior strong concise version, this final wording adds about 77 chars / 20 tokens to cover the review nuance that docs/source should be consulted before understanding OpenClaw behavior during task execution, not just before answering a direct question.

Real behavior proof

Behavior addressed: A question like "How does the daily note work for you?" can look like a user-memory question, but it is also an OpenClaw runtime behavior question. The agent should consult OpenClaw docs/source before treating AGENTS.md, workspace notes, profile/memory context, or memory tools as the source of OpenClaw design/implementation knowledge.

Real environment tested: Local OpenClaw checkout on macOS, branch sutrah/self-knowledge-docs-prompt, commit b47c45621b, embedded openclaw agent --local, isolated temp state/workspace under /private/tmp/openclaw-proof-90882 to avoid mutating the user's live ~/.openclaw.

Exact steps or command run after this patch:

OPENCLAW_STATE_DIR=/private/tmp/openclaw-proof-90882/state \
OPENCLAW_CONFIG_PATH=/private/tmp/openclaw-proof-90882/state/openclaw.json \
pnpm openclaw agent --local --agent main \
  --session-key self-knowledge-docs-understanding-proof-90882b \
  --model zai/glm-5.1 \
  --message "How does the daily note work for you?" \
  --json --timeout 300

Evidence after fix:

The live run completed successfully on provider=zai, model=glm-5.1, session 097c3d9f-3d77-4cf6-a921-2c15f2f1d1f5.
The trace starts by classifying the request as OpenClaw behavior and says it will check docs first: Let me check the docs to understand how daily notes work in OpenClaw.
The first tool turn searched local docs and also checked the actual isolated workspace state with ls /private/tmp/openclaw-proof-90882/workspace/memory/, which returned no memory dir.
The trace then searched docs for daily-note, memory, heartbeat, workspace, and project-context terms, and read docs/concepts/memory.md before producing the final answer.
Tool summary: 10 calls, tools exec and read, 0 failures.

Observed result after fix: The zai/glm-5.1 live run searched/read OpenClaw docs before answering the daily-note question, verified the isolated workspace's current memory/ state, and answered as an OpenClaw runtime behavior explanation. It did not answer first from workspace AGENTS.md context or external note/memory tooling.

What was not tested: This did not restart the user's production Gateway or mutate their real OpenClaw state; the live proof used the embedded local agent with isolated copied config/auth state.

clawsweeper · 2026-06-06T08:38:35Z

Codex review: passed. Reviewed June 18, 2026, 11:37 PM ET / 03:37 UTC.

Summary
This PR replaces the generated Documentation prompt wording with self-knowledge docs-authority guidance and updates prompt tests plus the system-prompt docs.

PR surface: Source 0, Tests +27, Docs +6. Total +33 across 4 files.

Reproducibility: yes. from source for the prompt gap: current main and v2026.6.8 have only broad docs-first wording, while the linked issue provides a concrete daily-note self-knowledge failure example. I did not run a fresh current-main live model conversation in this read-only review.

Review metrics: 1 noteworthy metric.

Prompt budget: +329 chars, about +83 tokens vs current main. The Documentation section is included in non-minimal agent prompts, so the small prompt-cost increase is useful maintainer context before merge.

Root-cause cluster
Relationship: fixed_by_candidate
Canonical: #90713
Summary: The open issue tracks the missing self-knowledge docs precedence rule; this PR is the active generated-prompt fix candidate, and the earlier AGENTS-only PR is closed as superseded.

Members:

canonical: System prompt should instruct agent to read docs before answering self-knowledge questions #90713 - The issue describes the central user problem and is explicitly closed by this PR.
superseded: docs: add self-knowledge rule to system prompt #90719 - The closed unmerged PR changed only AGENTS.md and was superseded by this generated-prompt PR.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🦞 diamond lobster
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

none.

Next step before merge

[P2] No repair lane is needed because there are no actionable findings and the PR is already under maintainer-requested automerge handling.

Security
Cleared: The diff is limited to prompt wording, prompt tests, and docs, with no dependency, workflow, permission, package, secret-handling, or code-execution surface change.

Review details

Best possible solution:

Land this generated prompt, test, and docs change if maintainers accept the small prompt-budget steering, then let the linked issue close after merge.

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

Yes from source for the prompt gap: current main and v2026.6.8 have only broad docs-first wording, while the linked issue provides a concrete daily-note self-knowledge failure example. I did not run a fresh current-main live model conversation in this read-only review.

Is this the best way to solve the issue?

Yes. Updating the shared generated Documentation prompt with matching tests and docs is the right layer; the earlier AGENTS-only approach was superseded because it did not change the runtime prompt source.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against ae6e1fa4d2d5.

Label changes

Label changes:

add status: 🚀 automerge armed: This PR is in ClawSweeper's automerge lane. Sufficient (live_output): The PR body provides sufficient live-output proof: an exact after-fix isolated local agent command plus observed trace details showing docs search/read before answering.
remove status: 👀 ready for maintainer look: Current PR status label is status: 🚀 automerge armed.

Label justifications:

P3: This is a low-risk prompt and documentation answer-quality fix with no urgent runtime, delivery, auth, migration, or security impact shown.
rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
status: 🚀 automerge armed: This PR is in ClawSweeper's automerge lane. Sufficient (live_output): The PR body provides sufficient live-output proof: an exact after-fix isolated local agent command plus observed trace details showing docs search/read before answering.
proof: sufficient: Contributor real behavior proof is sufficient. The PR body provides sufficient live-output proof: an exact after-fix isolated local agent command plus observed trace details showing docs search/read before answering.

Evidence reviewed

PR surface:

Source 0, Tests +27, Docs +6. Total +33 across 4 files.

View PR surface stats

Area	Files	Added	Removed	Net
Source	1	4	4	0
Tests	2	32	5	+27
Docs	1	9	3	+6
Config	0	0	0	0
Generated	0	0	0	0
Other	0	0	0	0
Total	4	45	12	+33

What I checked:

Repository policy read and applied: Root AGENTS.md and the scoped src/agents and docs guides were read; their review guidance drove the prompt-code, tests, docs, related-item, and proof checks. (AGENTS.md:1, ae6e1fa4d2d5)
Current main lacks the specific self-knowledge precedence rule: The current buildDocsSection still emits only the broad local-docs-first or mirror-first line and does not mention self-knowledge, AGENTS.md, workspace/profile/memory notes, or memory_search precedence. (src/agents/system-prompt.ts:613, ae6e1fa4d2d5)
PR head implements the generated prompt change: The PR head replaces the broad Documentation line with docs-authority wording for both local-docs and public-docs modes while preserving config and status guidance. (src/agents/system-prompt.ts:592, 88a7db5d2a56)
PR tests cover the prompt behavior: The PR head asserts local docs, public docs, read-tool casing, concise wording, and the intended treatment of AGENTS.md/project context, workspace/profile/memory notes, and memory_search. (src/agents/system-prompt.test.ts:509, 88a7db5d2a56)
PR docs match the generated prompt behavior: The PR head updates the system-prompt concept page to explain that docs are authoritative before the model treats workspace or memory context as OpenClaw implementation knowledge. Public docs: docs/concepts/system-prompt.md. (docs/concepts/system-prompt.md:317, 88a7db5d2a56)
Shared runtime caller path checked: CLI-backed runs pass resolved docsPath/sourcePath into buildCliAgentSystemPrompt, so the change targets a live generated prompt path rather than a docs-only surface. (src/agents/cli-runner/prepare.ts:688, ae6e1fa4d2d5)

Likely related people:

vincentkoc: Current blame for buildDocsSection, adjacent prompt tests, and the system-prompt docs points to a recent area-wide commit; Vincent also issued the maintainer automerge request on this PR. (role: recent area contributor; confidence: high; commits: 15e101137d90; files: src/agents/system-prompt.ts, src/agents/system-prompt.test.ts, docs/concepts/system-prompt.md)
steipete: git log -S shows Peter Steinberger introduced the enriched system-prompt docs guidance that this PR extends. (role: historical prompt-surface contributor; confidence: high; commits: e9a08dc50770; files: src/agents/system-prompt.ts, src/agents/system-prompt.test.ts, docs/concepts/system-prompt.md)
Takhoffman: Recent history shows Tak Hoffman changed nearby system-prompt and prompt-test surfaces around assistant directives and bootstrap behavior. (role: adjacent prompt/runtime contributor; confidence: medium; commits: 81818df1b483, cc5c691f0069; files: src/agents/system-prompt.ts, src/agents/system-prompt.test.ts)

What the crustacean ranks mean

🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

ClawSweeper keeps one durable marker-backed review comment per issue or PR.
Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
Maintainers can also comment @clawsweeper review to request a fresh review only.
Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

SutraHsing · 2026-06-06T08:59:03Z

@clawsweeper re-review

clawsweeper · 2026-06-06T08:59:06Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

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/27058071628
Updated: 2026-06-06T09:07:51.477Z

vincentkoc · 2026-06-19T03:09:37Z

/clownfish automerge

vincentkoc · 2026-06-19T03:14:02Z

Clownfish is on the reef for this PR. 🐠

I tagged clownfish:automerge and sent ClawSweeper over this exact head. If the sweep finds rough coral, failing checks, or needs-human, I will take another bounded repair lap and ask for a fresh review.

A maintainer can call /clownfish stop any time and I will drift this back to human review.

vincentkoc · 2026-06-19T03:30:17Z

/clownfish automerge

vincentkoc · 2026-06-19T03:31:12Z

Clownfish is on the reef for this PR. 🐠

I tagged clownfish:automerge and sent ClawSweeper over this exact head. If the sweep finds rough coral, failing checks, or needs-human, I will take another bounded repair lap and ask for a fresh review.

A maintainer can call /clownfish stop any time and I will drift this back to human review.

clawsweeper · 2026-06-19T03:38:40Z

🦞✅
ClawSweeper merged this PR after the passing review.

Source: clawsweeper[bot]
Feedback: structured ClawSweeper verdict: pass (sha=88a7db5d2a5678f33ff9c4b03351b45f79060c34)
Merge status: merged by ClawSweeper automerge
Merged at: 2026-06-19T03:38:37Z
Merge commit: dae06a203f1a

What merged:

This PR replaces the generated Documentation prompt wording with self-knowledge docs-authority guidance and updates prompt tests plus the system-prompt docs.
PR surface: Source 0, Tests +27, Docs +6. Total +33 across 4 files.
Reproducibility: yes. from source for the prompt gap: current main and v2026.6.8 have only broad docs-first ... ledge failure example. I did not run a fresh current-main live model conversation in this read-only review.

Automerge notes:

PR branch already contained follow-up commit before automerge: fix: strengthen self-knowledge docs prompt
PR branch already contained follow-up commit before automerge: test: narrow cli prompt tool assertion
PR branch already contained follow-up commit before automerge: fix: condense self-knowledge docs prompt
PR branch already contained follow-up commit before automerge: fix: clarify self-knowledge docs authority
PR branch already contained follow-up commit before automerge: Merge branch 'main' into sutrah/self-knowledge-docs-prompt

The automerge loop is complete.

Automerge progress:

2026-06-19 03:38:13 UTC review passed 88a7db5d2a56 (structured ClawSweeper verdict: pass (sha=88a7db5d2a5678f33ff9c4b03351b45f79060...)

2026-06-19 03:38:39 UTC merged 88a7db5d2a56 (merged by ClawSweeper automerge)

Summary: - This PR replaces the generated Documentation prompt wording with self-knowledge docs-authority guidance and updates prompt tests plus the system-prompt docs. - PR surface: Source 0, Tests +27, Docs +6. Total +33 across 4 files. - Reproducibility: yes. from source for the prompt gap: current main and v2026.6.8 have only broad docs-first ... ledge failure example. I did not run a fresh current-main live model conversation in this read-only review. Automerge notes: - PR branch already contained follow-up commit before automerge: fix: strengthen self-knowledge docs prompt - PR branch already contained follow-up commit before automerge: test: narrow cli prompt tool assertion - PR branch already contained follow-up commit before automerge: fix: condense self-knowledge docs prompt - PR branch already contained follow-up commit before automerge: fix: clarify self-knowledge docs authority - PR branch already contained follow-up commit before automerge: Merge branch 'main' into sutrah/self-knowledge-docs-prompt Validation: - ClawSweeper review passed for head 88a7db5. - Required merge gates passed before the squash merge. Prepared head SHA: 88a7db5 Review: openclaw#90882 (comment) Co-authored-by: Sutra Hsing <sutrahsing@163.com> Co-authored-by: sutra <sutrahsing@163.com>

fix: add self-knowledge docs rule to system prompt

2be3be4

openclaw-barnacle Bot added docs Improvements or additions to documentation agents Agent runtime and tooling size: XS proof: supplied External PR includes structured after-fix real behavior proof. labels Jun 6, 2026

clawsweeper Bot added the rating: 🌊 off-meta tidepool PR readiness rating does not apply to this item. label Jun 6, 2026

fix: strengthen self-knowledge docs prompt

4eb024d

test: narrow cli prompt tool assertion

3ef9870

openclaw-barnacle Bot added proof: supplied External PR includes structured after-fix real behavior proof. and removed triage: needs-real-behavior-proof Candidate: external PR needs after-fix proof from a real setup. labels Jun 6, 2026

clawsweeper Bot added the proof: sufficient ClawSweeper judged the real behavior proof convincing. label Jun 6, 2026

fix: condense self-knowledge docs prompt

2dec719

fix: clarify self-knowledge docs authority

b47c456

openclaw-barnacle Bot added proof: supplied External PR includes structured after-fix real behavior proof. and removed triage: needs-real-behavior-proof Candidate: external PR needs after-fix proof from a real setup. labels Jun 6, 2026

Merge branch 'main' into sutrah/self-knowledge-docs-prompt

88a7db5

openclaw-barnacle Bot removed the proof: sufficient ClawSweeper judged the real behavior proof convincing. label Jun 6, 2026

clawsweeper Bot added the proof: sufficient ClawSweeper judged the real behavior proof convincing. label Jun 6, 2026

openclaw-barnacle Bot removed the proof: sufficient ClawSweeper judged the real behavior proof convincing. label Jun 6, 2026

clawsweeper Bot added the proof: sufficient ClawSweeper judged the real behavior proof convincing. label Jun 6, 2026

This was referenced Jun 14, 2026

docs: add self-knowledge rule to system prompt #90719

Closed

System prompt should instruct agent to read docs before answering self-knowledge questions #90713

Closed

vincentkoc added the clownfish:automerge Maintainer opted this Clownfish PR into bounded ClawSweeper-reviewed automerge label Jun 19, 2026

vincentkoc added the clawsweeper:automerge Maintainer opted this PR into bounded ClawSweeper-reviewed automerge label Jun 19, 2026

vincentkoc mentioned this pull request Jun 19, 2026

chore(clownfish): record automerge review dispatch openclaw/clownfish#121

Merged

clawsweeper Bot added status: 🚀 automerge armed This PR is in ClawSweeper's automerge lane. and removed status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. labels Jun 19, 2026

clawsweeper Bot merged commit dae06a2 into openclaw:main Jun 19, 2026
214 of 218 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

fix: add self-knowledge docs rule to system prompt#90882

fix: add self-knowledge docs rule to system prompt#90882
clawsweeper[bot] merged 6 commits into
openclaw:mainfrom
SutraHsing:sutrah/self-knowledge-docs-prompt

SutraHsing commented Jun 6, 2026 •

edited

Loading

Uh oh!

clawsweeper Bot commented Jun 6, 2026 •

edited

Loading

Uh oh!

SutraHsing commented Jun 6, 2026

Uh oh!

clawsweeper Bot commented Jun 6, 2026 •

edited

Loading

Uh oh!

vincentkoc commented Jun 19, 2026

Uh oh!

vincentkoc commented Jun 19, 2026

Uh oh!

vincentkoc commented Jun 19, 2026

Uh oh!

vincentkoc commented Jun 19, 2026

Uh oh!

Uh oh!

clawsweeper Bot commented Jun 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Uh oh!

Conversation

SutraHsing commented Jun 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Verification

Prompt size

Real behavior proof

Uh oh!

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

Uh oh!

Uh oh!

SutraHsing commented Jun 6, 2026

Uh oh!

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

Uh oh!

Uh oh!

vincentkoc commented Jun 19, 2026

Uh oh!

vincentkoc commented Jun 19, 2026

Uh oh!

vincentkoc commented Jun 19, 2026

Uh oh!

vincentkoc commented Jun 19, 2026

Uh oh!

Uh oh!

clawsweeper Bot commented Jun 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

SutraHsing commented Jun 6, 2026 •

edited

Loading

clawsweeper Bot commented Jun 6, 2026 •

edited

Loading

clawsweeper Bot commented Jun 6, 2026 •

edited

Loading