PR #52038: feat(config): add agents.defaults.systemPrompt and rules for config-injectable agent rules

• Repository: openclaw/openclaw
• Author: ytang928
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/52038

Description (problem / solution / changelog)

Summary

Add systemPrompt (string) and rules (string[]) fields to agents.defaults and agents.list[], allowing users to inject behavioral rules and safety guidelines into the agent system prompt from config instead of (or in addition to) workspace bootstrap files like AGENTS.md.

Problem: Currently, agent behavioral rules live exclusively in workspace files (AGENTS.md, SOUL.md). This ties rules to the workspace, makes central management across multiple workspaces difficult, and provides no way to manage rules via Control UI or openclaw config set.

Solution:

• systemPrompt: a block of text appended to the system prompt after workspace bootstrap files
• rules: an array of strings rendered as a numbered list and appended after systemPrompt
• Per-agent overrides via agents.list[].systemPrompt / agents.list[].rules
• Fully backward compatible — empty/absent values inject nothing

Config example

{
  "agents": {
    "defaults": {
      "systemPrompt": "You are a safety-conscious assistant.",
      "rules": [
        "Do not exfiltrate private data.",
        "Do not run destructive commands without asking.",
        "When in doubt, ask."
      ]
    },
    "list": [
      {
        "id": "support",
        "systemPrompt": "You are a customer support agent.",
        "rules": ["Always be polite.", "Escalate billing issues."]
      }
    ]
  }
}

Closes #50103

Change Type

• Feature

Scope

• Gateway
• API

User-visible / Behavior Changes

• New config fields agents.defaults.systemPrompt and agents.defaults.rules
• New per-agent config fields agents.list[].systemPrompt and agents.list[].rules
• Config-injected content appears in the system prompt after workspace bootstrap files and channel/group system prompts
• Per-agent values override (not merge with) defaults

Security Impact

None. This adds a new way to inject rules from user-controlled config into the system prompt. The content flows through the same extraSystemPrompt pipeline as existing channel systemPrompt fields. No new permissions, secrets handling, network calls, or command execution surface.

Repro + Verification

1. Add systemPrompt and/or rules to agents.defaults in openclaw.json
2. Start a session — the injected text appears in the system prompt after bootstrap files
3. Add per-agent overrides in agents.list[] — agent-specific values take precedence

Evidence

• Schema validation tests: 5 new tests in src/config/zod-schema.agent-defaults.test.ts
• Prompt resolution tests: 9 new tests in src/auto-reply/reply/get-reply-run.config-system-prompt.test.ts
• All existing tests pass (scoped: agent-scope, schema help quality)
• pnpm check passes (format, lint, typecheck, all boundary checks)

Human Verification

• Verified schema accepts valid systemPrompt (string) and rules (string[])
• Verified schema rejects invalid types (number for systemPrompt, string for rules)
• Verified per-agent override takes precedence over defaults
• Verified case-insensitive agent ID matching
• Verified empty/whitespace-only values inject nothing
• Did not verify: runtime end-to-end with a live gateway session (no access to running instance)

Compatibility / Migration

Fully backward compatible. Both fields are optional and default to undefined (no injection). Existing configs are unaffected.

Failure Recovery

Revert this commit. No migration or config changes needed.

Risks and Mitigations

Low risk. The change is additive — no existing behavior is modified. The injection point follows the same pattern as existing channel systemPrompt fields.

Changed files

• docs/.generated/config-baseline.json (modified, +74/-0)
• docs/.generated/config-baseline.jsonl (modified, +7/-1)
• src/agents/cli-runner/helpers.ts (modified, +6/-0)
• src/agents/config-system-prompt.ts (added, +30/-0)
• src/agents/pi-embedded-runner/run/attempt.ts (modified, +6/-0)
• src/agents/pi-embedded-runner/system-prompt.ts (modified, +3/-0)
• src/agents/system-prompt.test.ts (modified, +26/-0)
• src/agents/system-prompt.ts (modified, +7/-0)
• src/auto-reply/reply/get-reply-run.config-system-prompt.test.ts (added, +99/-0)
• src/config/schema.help.ts (modified, +4/-0)
• src/config/schema.labels.ts (modified, +4/-0)
• src/config/types.agent-defaults.ts (modified, +13/-0)
• src/config/types.agents.ts (modified, +10/-0)
• src/config/zod-schema.agent-defaults.test.ts (modified, +41/-0)
• src/config/zod-schema.agent-defaults.ts (modified, +2/-0)
• src/config/zod-schema.agent-runtime.ts (modified, +2/-0)