OpenClawDocs
On this page

On this page

View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Plugin guides

Agent Guidance

Agent Guidance

Agent Guidance shares instruction files across selected agents. OpenClaw adds their text directly to the prompt sent to the model, before or after its normal instructions. The plugin does not edit AGENTS.md, SOUL.md, or other workspace files. Each agent keeps its own instructions, personality, and memory.

When to use it

What you need Use
Instructions for one agent That agent's workspace AGENTS.md
Additional recognized context files inside a workspace The bootstrap-extra-files hook
One separately maintained set of instructions for several agents Agent Guidance
Instructions that depend on custom runtime logic A plugin using prompt hooks

Without this plugin, you can copy shared instructions into each agent's workspace files and keep the copies in sync, or write a plugin using the existing before_prompt_build hook. Agent Guidance packages the shared-file approach so you can configure it without writing code. It adds no new Plugin SDK hooks.

Example: two agents, one shared file

Suppose main answers everyday questions and research investigates topics in depth. Both should cite sources, but each should keep its own working style.

Before With Agent Guidance
main workspace Its own instructions plus a copy of the citation guidance Its own instructions
research workspace Its own instructions plus another copy of the citation guidance Its own instructions
Shared guidance Update both copies when the guidance changes Edit one instructions.md and reload the plugin

The configuration below adds the same shared text to both agents' prompts. An agent not listed in agents receives none of it. Existing workspace files are left unchanged; remove any old duplicate guidance yourself when migrating.

Configure

The plugin is disabled by default. Create an operator-controlled directory outside agent-writable workspaces, protect its files and ancestor directories with filesystem permissions, then add an entry to your configuration:

json
{  "plugins": {    "entries": {      "agent-guidance": {        "enabled": true,        "hooks": {          "allowConversationAccess": true,          "allowPromptInjection": true        },        "config": {          "directory": "/srv/agent-guidance",          "agents": ["main", "research"],          "append": ["instructions.md"]        }      }    }  }}

If you use plugins.allow, also include agent-guidance in that list. On Windows, use an absolute Windows directory. The native before_prompt_build hook requires both permissions above, although this plugin ignores event content.

Example instructions.md:

text
Cite sources when doing research.Distinguish observations from assumptions.

agents contains exact, case-sensitive agent IDs, not sender identities. Use your existing agent IDs; this configuration does not create agents. Unselected agents and hooks without an agent ID receive no contribution. Instructions are sent to the configured model: never put secrets in them.

Files And Placement

  • directory: required absolute path. No environment expansion or workspace default.
  • agents: 1 to 64 distinct explicit agent IDs.
  • prepend: ordered relative file names placed before the normal system prompt through prependSystemContext.
  • append: ordered relative file names placed after the normal system prompt through appendSystemContext.

Placement controls text order, not tool permissions or guaranteed instruction precedence. Use append as in the example unless you need a prefix.

Configure 1 to 8 files across both placements. Each must be a nonempty UTF-8 regular file of at most 16 KiB; combined contributions are limited to 64 KiB, including the two newlines between files in each placement. Oversized content is rejected, not truncated. The model's context limits still apply.

File names use forward slashes, letters, digits, dots, underscores and hyphens. Traversal, duplicate names, symbolic/hard links, linked ancestor directories, nonregular files, malformed UTF-8 and NULs are rejected. These checks do not replace operator-managed permissions and are not a filesystem sandbox.

Update And Disable

Files are read once at plugin registration. Editing a file alone does not change the active snapshot. After editing, use native reload or restart:

sh
openclaw plugins reload agent-guidance

Separately mounted instruction files can be updated without rebuilding the plugin or image. Instructions baked into an immutable image still require a new image. There is no file watcher, per-turn read or remote configuration fetch.

Disable future contributions with openclaw plugins disable agent-guidance; re-enable with openclaw plugins enable agent-guidance. Previously submitted prompts cannot be recalled. Existing conversations can see new instructions after reload: this plugin does not pin instruction versions to sessions. Drain existing sessions before updates when stable session prompts are required.

Failure Behavior

A file-load error prevents registration of the entire contribution. Diagnostics identify the file's configured position without printing paths or content. OpenClaw can continue without a failed plugin: guidance is not a fail-closed policy gate, tool authorization or a guarantee of model obedience.

Failed reload does not guarantee that the previous instructions stay active. Native recovery restores plugin code/configuration, not external instruction bytes. Keep a known-good copy under operator control. After a bad edit, restore valid files, reload and verify the plugin before resuming dependent work.

See Managing plugins and Plugin architecture for native permissions and lifecycle.

Was this useful?