feat: wire customInstructions from plugin config (#181)

* feat: wire customInstructions from plugin config

The customInstructions parameter threads through all 4 prompt builders
(buildLeafSummaryPrompt, buildD1Prompt, buildD2Prompt, buildD3PlusPrompt)
but is never read from config. This means operators cannot control
summarization tone or style without patching source.

Fix:
- Add customInstructions to LcmConfig type and resolver (config.ts)
- Read in resolveSummarize() chokepoint (engine.ts) with fallback:
  params.customInstructions || this.config.customInstructions || undefined
- Add to plugin schema and uiHints (openclaw.plugin.json)
- Add config test coverage (test/custom-instructions.test.ts)

Every summarization path (afterTurn, /compact, overflow recovery) gets
instructions automatically through the chokepoint without caller changes.

* fix: honor customInstructions overrides across summarizers

---------

Co-authored-by: Josh Lehman <[email protected]>

Author: jamebobob

openclaw.plugin.json

@@ -52,6 +52,10 @@
     "summaryMaxOverageFactor": {
       "label": "Summary Max Overage Factor",
       "help": "Maximum allowed overage factor for summaries relative to target tokens (default 3). Summaries exceeding this are deterministically truncated."
+    },
+    "customInstructions": {
+      "label": "Custom Instructions",
+      "help": "Natural language instructions injected into all summarization prompts (e.g., formatting rules, tone control)"
     }
   },
   "configSchema": {
@@ -127,6 +131,9 @@
       "summaryMaxOverageFactor": {
         "type": "number",
         "minimum": 1
+      },
+      "customInstructions": {
+        "type": "string"
       }
     }
   }

src/db/config.ts

@@ -46,6 +46,8 @@ export type LcmConfig = {
   maxAssemblyTokenBudget?: number;
   /** Maximum allowed overage factor for summaries relative to target tokens (default 3). */
   summaryMaxOverageFactor: number;
+  /** Custom instructions injected into all summarization prompts. */
+  customInstructions: string;
 };
 
 /** Safely coerce an unknown value to a finite number, or return undefined. */
@@ -195,5 +197,7 @@ export function resolveLcmConfig(
     summaryMaxOverageFactor:
       (env.LCM_SUMMARY_MAX_OVERAGE_FACTOR !== undefined ? parseFloat(env.LCM_SUMMARY_MAX_OVERAGE_FACTOR) : undefined)
         ?? toNumber(pc.summaryMaxOverageFactor) ?? 3,
+    customInstructions:
+      env.LCM_CUSTOM_INSTRUCTIONS?.trim() ?? toStr(pc.customInstructions) ?? "",
   };
 }

src/engine.ts

@@ -1238,10 +1238,14 @@ export class LcmContextEngine implements ContextEngine {
       };
     }
     try {
+      const customInstructions =
+        params.customInstructions !== undefined
+          ? params.customInstructions
+          : (this.config.customInstructions || undefined);
       const runtimeSummarizer = await createLcmSummarizeFromLegacyParams({
         deps: this.deps,
         legacyParams: lp,
-        customInstructions: params.customInstructions,
+        customInstructions,
       });
       if (runtimeSummarizer) {
         return { summarize: runtimeSummarizer.fn, summaryModel: runtimeSummarizer.model };
@@ -1278,6 +1282,7 @@ export class LcmContextEngine implements ContextEngine {
       const result = await createLcmSummarizeFromLegacyParams({
         deps: this.deps,
         legacyParams: { provider, model },
+        customInstructions: this.config.customInstructions || undefined,
       });
       if (!result) {
         return undefined;

test/custom-instructions.test.ts

@@ -0,0 +1,58 @@
+import { describe, it, expect } from "vitest";
+import manifest from "../openclaw.plugin.json" with { type: "json" };
+import { resolveLcmConfig } from "../src/db/config.js";
+
+describe("customInstructions config", () => {
+  it("defaults customInstructions to empty string", () => {
+    const config = resolveLcmConfig({}, {});
+    expect(config.customInstructions).toBe("");
+  });
+
+  it("reads customInstructions from plugin config", () => {
+    const config = resolveLcmConfig({}, {
+      customInstructions: "Write as a neutral documenter. Use third person.",
+    });
+    expect(config.customInstructions).toBe("Write as a neutral documenter. Use third person.");
+  });
+
+  it("env var overrides plugin config for customInstructions", () => {
+    const config = resolveLcmConfig(
+      { LCM_CUSTOM_INSTRUCTIONS: "env instructions" } as NodeJS.ProcessEnv,
+      { customInstructions: "plugin instructions" },
+    );
+    expect(config.customInstructions).toBe("env instructions");
+  });
+
+  it("trims whitespace from env var customInstructions", () => {
+    const config = resolveLcmConfig(
+      { LCM_CUSTOM_INSTRUCTIONS: "  trimmed  " } as NodeJS.ProcessEnv,
+      {},
+    );
+    expect(config.customInstructions).toBe("trimmed");
+  });
+
+  it("trims whitespace from plugin config customInstructions", () => {
+    const config = resolveLcmConfig({}, {
+      customInstructions: "  trimmed  ",
+    });
+    expect(config.customInstructions).toBe("trimmed");
+  });
+
+  it("falls through to default when plugin config value is empty string", () => {
+    const config = resolveLcmConfig({}, {
+      customInstructions: "   ",
+    });
+    expect(config.customInstructions).toBe("");
+  });
+
+  it("ignores non-string plugin config values", () => {
+    const config = resolveLcmConfig({}, {
+      customInstructions: 42,
+    });
+    expect(config.customInstructions).toBe("");
+  });
+
+  it("ships a manifest with customInstructions in schema", () => {
+    expect(manifest.configSchema.properties.customInstructions).toEqual({ type: "string" });
+  });
+});

test/engine.test.ts

@@ -46,6 +46,7 @@ function createTestConfig(databasePath: string): LcmConfig {
     timezone: "UTC",
     pruneHeartbeatOk: false,
     summaryMaxOverageFactor: 3,
+    customInstructions: "",
   };
 }
 
@@ -3106,6 +3107,69 @@ describe("LcmContextEngine fidelity and token budget", () => {
 // ── Compact token budget plumbing ───────────────────────────────────────────
 
 describe("LcmContextEngine.compact token budget plumbing", () => {
+  it("preserves explicit empty-string customInstructions overrides over config defaults", async () => {
+    const completeSpy = vi.fn(async () => ({
+      content: [{ type: "text", text: "summary output" }],
+    }));
+    const engine = createEngineWithDeps(
+      { customInstructions: "Write in third person." },
+      { complete: completeSpy },
+    );
+    const privateEngine = engine as unknown as {
+      resolveSummarize: (params: {
+        legacyParams?: Record<string, unknown>;
+        customInstructions?: string;
+      }) => Promise<{
+        summarize: (text: string, aggressive?: boolean) => Promise<string>;
+        summaryModel: string;
+      }>;
+    };
+
+    const { summarize } = await privateEngine.resolveSummarize({
+      legacyParams: { provider: "anthropic", model: "claude-opus-4-5" },
+      customInstructions: "",
+    });
+
+    await summarize("segment text");
+
+    const firstCall = completeSpy.mock.calls[0]?.[0] as
+      | { messages?: Array<{ content?: string }> }
+      | undefined;
+    const prompt = firstCall?.messages?.[0]?.content;
+    expect(typeof prompt).toBe("string");
+    expect(prompt).toContain("Operator instructions: (none)");
+    expect(prompt).not.toContain("Write in third person.");
+  });
+
+  it("forwards config customInstructions to large-file summarization", async () => {
+    const completeSpy = vi.fn(async () => ({
+      content: [{ type: "text", text: "summary output" }],
+    }));
+    const engine = createEngineWithDeps(
+      {
+        customInstructions: "Use terse factual prose.",
+        largeFileSummaryProvider: "anthropic",
+        largeFileSummaryModel: "claude-opus-4-5",
+      },
+      { complete: completeSpy },
+    );
+    const privateEngine = engine as unknown as {
+      resolveLargeFileTextSummarizer: () => Promise<((prompt: string) => Promise<string | null>) | undefined>;
+    };
+
+    const summarizeText = await privateEngine.resolveLargeFileTextSummarizer();
+    expect(summarizeText).toBeTypeOf("function");
+
+    await summarizeText!("Large file prompt");
+
+    const firstCall = completeSpy.mock.calls[0]?.[0] as
+      | { messages?: Array<{ content?: string }> }
+      | undefined;
+    const prompt = firstCall?.messages?.[0]?.content;
+    expect(typeof prompt).toBe("string");
+    expect(prompt).toContain("Operator instructions:\nUse terse factual prose.");
+  });
+
   it("fails when compact token budget is missing", async () => {
     const engine = createEngine();
     const sessionId = "session-missing-budget";