#systemPromptOverride usage

1 messages · Page 1 of 1 (latest)

empty kayak
#

Hi Krill — quick follow-up on systemPromptOverride before I wire up a second agent.

CC traced the source and found that systemPromptOverride fully replaces the system prompt
at runtime. The type definition comment says "primarily for prompt debugging and controlled
experiments."

My use case is different: I have a second agent (a maintenance/support agent, similar to
what you described in your Krill-starter recipe) with its own dedicated agentDir containing
AGENTS.md, SOUL.md, IDENTITY.md, and TOOLS.md. I want those files to load normally via
workspace injection on every session. But I also want to protect the agent's core identity
from being accidentally overwritten by a user who has shell access to the workspace.

Two questions:

  1. If I set systemPromptOverride on this agent, does workspace injection (AGENTS.md,
    SOUL.md etc.) still happen — or does the override fully bypass it?

  2. If the override bypasses workspace injection, what's the recommended pattern for
    protecting a second agent's instructions from user edits in the workspace, while still
    keeping the full workspace file loading behaviour?

Running v2026.4.15. Thanks.

nocturne basinBOT
paper mirageBOT
#

To help others find answers, you can mark your question as solved via Right click solution message -> Apps -> âś… Mark Solution

nocturne basinBOT
pseudo raptorBOT
#

Let me verify this in source instead of guessing.

#

The tricky bit is that “protect from shell edits” and “load from a writable workspace” are kind of at odds, so I’m checking the least-janky supported pattern.

#

I checked source on this, and for v2026.4.15 it is basically a full bypass.

Small nit first: those files are loaded from the agent’s workspace, not agentDir. agentDir is the per-agent state/auth dir.

  1. If you set agents.defaults.systemPromptOverride or agents.list[].systemPromptOverride, the normal OpenClaw-built system prompt is skipped. So the usual injected workspace bootstrap (AGENTS.md, SOUL.md, IDENTITY.md, TOOLS.md, etc.) is not part of the final model-facing prompt. Treat it as “replace everything”, not “append”.

  2. If you want full workspace loading and also want the core identity protected, I would not use systemPromptOverride for that. The sane pattern in 2026.4.15 is:

  • give that agent its own dedicated workspace and agentDir
  • leave systemPromptOverride unset
  • protect that workspace with OS ownership/permissions, or run the gateway under a separate service account

If someone can edit the exact workspace files the gateway reads, there is no config-only way to make those files immutable.

Advanced option: use an agent:bootstrap hook or prompt-mutation plugin to inject or replace protected instructions from a non-workspace location. The bundled bootstrap-extra-files hook does not solve this by itself, because it only loads files from inside the workspace.

Docs:
https://docs.openclaw.ai/gateway/configuration-reference#agentsdefaultssystempromptoverride

empty kayak
#

yes.. can you pls sketch a concrete layout for the second agent

pseudo raptorBOT
#

I want to make sure I don’t hand-wave the isolation bit, because “second agent” and “same Unix user” have a real limitation here.

#

Yep. I’d use this split:

Recommended layout

~/.openclaw/openclaw.json
~/.openclaw/agents/support/agent/          # auth + per-agent state, not prompt files
/srv/openclaw/support-workspace/
  AGENTS.md                                # locked, auto-injected
  SOUL.md                                  # locked, auto-injected
  IDENTITY.md                              # locked, auto-injected
  USER.md                                  # locked if you use it
  TOOLS.md                                 # locked or semi-locked
  HEARTBEAT.md                             # optional
  memory/                                  # normal memory files
  inbox/                                   # user-editable operational input
# 
  notes/                                   # user-editable notes/runbooks

Agent config

{
  agents: {
    list: [
      {
        id: "support",
        name: "Support",
        workspace: "/srv/openclaw/support-workspace",
        agentDir: "~/.openclaw/agents/support/agent"
        // leave systemPromptOverride unset
# 
      }
    ]
  }
}

What to lock down

Keep these root bootstrap files owned by the gateway user and not writable by other shell users:

  • AGENTS.md
  • SOUL.md
  • IDENTITY.md
  • USER.md (if used)
  • usually TOOLS.md too
#

Keep normal operational stuff elsewhere:

  • inbox/
  • notes/
  • memory/

That gives you the thing you want: core identity still loads automatically every session, but editable ops content lives outside the identity files.

Permission model

Good default on the host:

  • workspace dir: 700
  • bootstrap files: 600
  • config/state: 700 dir, 600 files

If another local user needs to drop input for the agent, give them access only to inbox/ or notes/, not to the root bootstrap files.

#

Important limitation

If the person with shell access is the same Unix user that runs OpenClaw, you cannot really protect those files with a second-agent-only config trick. In that case, the real answer is:

  • run that support agent under a separate service account / separate OpenClaw home
  • or run it as a separate gateway/profile entirely

That is the only real boundary.

If you want extra auto-injected files

Use hooks only for non-core stuff. A custom agent:bootstrap hook can add/replace injected files, but I would still keep the canonical identity in the locked root files above.

Docs:
https://docs.openclaw.ai/concepts/multi-agent
https://docs.openclaw.ai/concepts/agent-workspace
https://docs.openclaw.ai/help/environment#openclaw_home