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

SutraHsing · web-flow · commit dae06a203f1a · 2026-06-19T03:38:36.000Z
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: #90882 (comment) Co-authored-by: Sutra Hsing <sutrahsing@163.com> Co-authored-by: sutra <sutrahsing@163.com>
diff --git a/docs/concepts/system-prompt.md b/docs/concepts/system-prompt.md
@@ -315,9 +315,15 @@ The same section also includes the OpenClaw source location. Git checkouts expos
 source root so the agent can inspect code directly. Package installs include the GitHub
 source URL and tell the agent to review source there whenever the docs are incomplete or
 stale. The prompt also notes the public docs mirror, community Discord, and ClawHub
-([https://clawhub.ai](https://clawhub.ai)) for skills discovery. It tells the model to
-consult docs first for OpenClaw behavior, commands, configuration, or architecture, and to
-run `openclaw status` itself when possible (asking the user only when it lacks access).
+([https://clawhub.ai](https://clawhub.ai)) for skills discovery. It frames docs as the
+authority for OpenClaw self-knowledge before the model understands how OpenClaw works,
+including memory/daily notes, sessions, tools, Gateway, config, commands, or project
+context. The prompt tells the model to use local docs (or the docs mirror when local docs
+are unavailable) first, and to treat AGENTS.md, project context, workspace/profile/memory
+notes, and `memory_search` as instruction context or user memory rather than OpenClaw
+design or implementation knowledge. If docs are silent or stale, the model should say so
+and inspect source. The prompt also tells the model to run `openclaw status` itself when
+possible, asking the user only when it lacks access.
 For configuration specifically, it points agents to the `gateway` tool action
 `config.schema.lookup` for exact field-level docs and constraints, then to
 `docs/gateway/configuration.md` and `docs/gateway/configuration-reference.md`
diff --git a/src/agents/cli-runner/prepare.test.ts b/src/agents/cli-runner/prepare.test.ts
@@ -2185,7 +2185,7 @@ describe("shouldSkipLocalCliCredentialEpoch", () => {
       expect(createMcpLoopbackServerConfig).not.toHaveBeenCalled();
       expect(resolveMcpLoopbackScopedTools).not.toHaveBeenCalled();
       expect(context.systemPrompt).not.toContain("## Memory Recall");
-      expect(context.systemPrompt).not.toContain("memory_search");
+      expect(context.systemPrompt).not.toMatch(/^- memory_search\b/m);
       expect(context.systemPromptReport.tools.entries).toEqual([]);
       expect(context.promptToolNamesHash).toBeUndefined();
       expect(context.preparedBackend.env).toBeUndefined();
diff --git a/src/agents/system-prompt.test.ts b/src/agents/system-prompt.test.ts
@@ -507,7 +507,9 @@ describe("buildAgentSystemPrompt", () => {
     expect(prompt).toContain("If a skill's <version> differs from a previous turn");
     expect(prompt).toContain("If several apply, choose the most specific.");
     expect(prompt).toContain("Docs: /tmp/openclaw/docs");
-    expect(prompt).toContain("OpenClaw behavior/config/architecture: read local docs first.");
+    expect(prompt).toContain(
+      "Docs are authoritative for OpenClaw self-knowledge: before understanding how OpenClaw works (memory/daily notes, sessions, tools, Gateway, config, commands, project context), use `Read` or search local docs first; treat AGENTS.md/project context, workspace/profile/memory notes, and `memory_search` as instruction context or user memory, not OpenClaw design/implementation knowledge.",
+    );
   });
 
   it("includes docs guidance when docsPath is provided", () => {
@@ -520,8 +522,30 @@ describe("buildAgentSystemPrompt", () => {
     expect(prompt).toContain("## Documentation");
     expect(prompt).toContain("Docs: /tmp/openclaw/docs");
     expect(prompt).toContain("Source: /tmp/openclaw");
-    expect(prompt).toContain("OpenClaw behavior/config/architecture: read local docs first.");
-    expect(prompt).toContain("If docs are stale/incomplete, inspect local source.");
+    expect(prompt).toContain(
+      "Docs are authoritative for OpenClaw self-knowledge: before understanding how OpenClaw works (memory/daily notes, sessions, tools, Gateway, config, commands, project context), use `read` or search local docs first; treat AGENTS.md/project context, workspace/profile/memory notes, and `memory_search` as instruction context or user memory, not OpenClaw design/implementation knowledge.",
+    );
+    expect(prompt).toContain("If docs are silent/stale, say so and inspect local source.");
+  });
+
+  it("keeps self-knowledge docs guidance concise and authoritative", () => {
+    const prompt = buildAgentSystemPrompt({
+      workspaceDir: "/tmp/openclaw",
+      docsPath: "/tmp/openclaw/docs",
+      sourcePath: "/tmp/openclaw",
+      toolNames: ["read", "memory_search"],
+    });
+    const docsStart = prompt.indexOf("## Documentation");
+    const nextSection = prompt.indexOf("\n## ", docsStart + 1);
+    const docsSection = prompt.slice(docsStart, nextSection);
+
+    expect(prompt).toContain(
+      "Docs are authoritative for OpenClaw self-knowledge: before understanding how OpenClaw works (memory/daily notes, sessions, tools, Gateway, config, commands, project context), use `read` or search local docs first; treat AGENTS.md/project context, workspace/profile/memory notes, and `memory_search` as instruction context or user memory, not OpenClaw design/implementation knowledge.",
+    );
+    expect(docsSection.length).toBeLessThan(840);
+    expect(prompt).not.toContain("Self-knowledge rule: for questions about");
+    expect(prompt).not.toContain("Treat questions about daily notes");
+    expect(prompt).not.toContain("never answer from AGENTS.md/project context");
   });
 
   it("falls back to public docs and GitHub source guidance when local docs are unavailable", () => {
@@ -531,7 +555,10 @@ describe("buildAgentSystemPrompt", () => {
 
     expect(prompt).toContain("Docs: https://docs.openclaw.ai");
     expect(prompt).toContain("Source: https://github.com/openclaw/openclaw");
-    expect(prompt).toContain("If docs are stale/incomplete, inspect GitHub source.");
+    expect(prompt).toContain(
+      "Docs are authoritative for OpenClaw self-knowledge: before understanding how OpenClaw works (memory/daily notes, sessions, tools, Gateway, config, commands, project context), use the docs mirror first when web tooling is available; treat AGENTS.md/project context, workspace/profile/memory notes, and `memory_search` as instruction context or user memory, not OpenClaw design/implementation knowledge.",
+    );
+    expect(prompt).toContain("If docs are silent/stale, say so and inspect GitHub source.");
   });
 
   it("includes workspace notes when provided", () => {
diff --git a/src/agents/system-prompt.ts b/src/agents/system-prompt.ts
@@ -610,12 +610,12 @@ function buildDocsSection(params: {
     docsPath ? "Mirror: https://docs.openclaw.ai" : undefined,
     sourcePath ? `Source: ${sourcePath}` : "Source: https://github.com/openclaw/openclaw",
     docsPath
-      ? "OpenClaw behavior/config/architecture: read local docs first."
-      : "OpenClaw behavior/config/architecture: read docs mirror first.",
+      ? `Docs are authoritative for OpenClaw self-knowledge: before understanding how OpenClaw works (memory/daily notes, sessions, tools, Gateway, config, commands, project context), use \`${params.readToolName}\` or search local docs first; treat AGENTS.md/project context, workspace/profile/memory notes, and \`memory_search\` as instruction context or user memory, not OpenClaw design/implementation knowledge.`
+      : "Docs are authoritative for OpenClaw self-knowledge: before understanding how OpenClaw works (memory/daily notes, sessions, tools, Gateway, config, commands, project context), use the docs mirror first when web tooling is available; treat AGENTS.md/project context, workspace/profile/memory notes, and `memory_search` as instruction context or user memory, not OpenClaw design/implementation knowledge.",
     "Config fields: use `gateway` action `config.schema.lookup`; broader config docs: `docs/gateway/configuration.md`, `docs/gateway/configuration-reference.md`.",
     sourcePath
-      ? "If docs are stale/incomplete, inspect local source."
-      : "If docs are stale/incomplete, inspect GitHub source.",
+      ? "If docs are silent/stale, say so and inspect local source."
+      : "If docs are silent/stale, say so and inspect GitHub source.",
     "Diagnosing issues: run `openclaw status` when possible; ask user only if blocked.",
     "",
   ];
