From 55185123e386d6a102745061a0574dabfe6fd134 Mon Sep 17 00:00:00 2001 From: dtzp555 Date: Thu, 19 Mar 2026 08:00:19 +1000 Subject: [PATCH] docs: expand README with full file reference and FAQ Co-Authored-By: Claude Sonnet 4.6 --- README.md | 151 ++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 123 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index 1c2afe6..66a4ce3 100644 --- a/README.md +++ b/README.md @@ -1,48 +1,143 @@ -# openclaw-agent-template +# OpenClaw Agent Template -A minimal, opinionated starter kit for creating OpenClaw agents — drop it into any workspace and your agent has identity, memory, and operating rules from day one. +A starter kit for creating new OpenClaw agents. Get a fully configured agent running in under 5 minutes. --- -## Quick Start +## Quick Start (3 Steps) + +### Step 1 — Clone this template ```bash -# 1. Clone this template -git clone https://github.com/dtzp555-max/openclaw-agent-template.git my-agent -cd my-agent - -# 2. Copy the files into your workspace's agent config directory -cp -r . /path/to/your/workspace/.openclaw/agent/ - -# 3. Reload your OpenClaw gateway to pick up the new config -openclaw reload # or restart your Claude Code session +# Copy the template files to your agent's workspace directory +cp -r openclaw-agent-template/ ~/.openclaw/projects/YOUR_AGENT_NAME/ ``` -Then open `IDENTITY.md` and replace the `[PLACEHOLDERS]` with your agent's actual name, emoji, and vibe. +Or if you're setting up inside an existing project: + +```bash +# Copy just the agent config files into your project +cp openclaw-agent-template/{SOUL.md,IDENTITY.md,USER.md,AGENTS.md,TOOLS.md,MEMORY.md} your-project/ +cp -r openclaw-agent-template/memory/ your-project/memory/ +``` + +### Step 2 — Fill in the placeholders + +Open each file and replace the `[PLACEHOLDER]` values with your agent's actual details: + +| File | What to fill in | +|------|----------------| +| `IDENTITY.md` | Agent name, emoji, creature, vibe | +| `USER.md` | Your name, pronouns, timezone, preferences | +| `SOUL.md` | Personality description, workspace name | +| `AGENTS.md` | Workspace name, agent role, capabilities | +| `TOOLS.md` | Workspace-specific tools and restrictions | +| `MEMORY.md` | Leave empty — the agent will populate this | +| `memory/CURRENT_STATE.md` | Leave empty — the agent will populate this | + +Search for `[` to find all placeholders across files: + +```bash +grep -r "\[" . --include="*.md" -l +``` + +### Step 3 — Restart the gateway + +```bash +openclaw gateway restart +# or via the OpenClaw app: Settings -> Gateway -> Restart +``` + +Your agent is ready. Open a new chat and it will introduce itself. --- -## Files +## File Reference -| File | Purpose | -|------|---------| -| `SOUL.md` | Core behavior contract — message prefix rules, principles, continuity recovery | -| `IDENTITY.md` | Who the agent is — name, emoji, creature, vibe, specializations | -| `USER.md` | Who the agent serves — working style, expertise, preferences | -| `AGENTS.md` | Workspace rules — session startup, memory policy, safety guardrails | -| `TOOLS.md` | Available tools and usage guidelines | -| `MEMORY.md` | Long-term memory — decisions, context, learnings across sessions | -| `memory/CURRENT_STATE.md` | Short-term state — what's in flight, blocked, or next | +### `SOUL.md` — Behavioral DNA +Defines how the agent communicates and recovers from context loss. Contains: +- **Message prefix format** — the emoji + name pattern used in every message +- **Core truths** — non-negotiable facts the agent holds about itself +- **Vibe** — personality description that shapes tone +- **Continuity recovery protocol** — step-by-step instructions for re-orienting after a context gap + +**Edit this when:** you want to change the agent's personality, communication style, or recovery behavior. + +--- + +### `IDENTITY.md` — Who the Agent Is +Defines the agent's name, emoji, creature, role, and specializations. + +**Edit this when:** the agent takes on new responsibilities or you want to update its self-description. + +--- + +### `USER.md` — Who the Agent Serves +Tells the agent about the person it's working with — expertise level, preferences, timezone, and working style. This helps the agent calibrate its responses. + +**Edit this when:** your working style changes, you want to add/remove preferences, or a new person starts working with the agent. + +--- + +### `AGENTS.md` — Workspace Map +Describes the workspace and all agents operating within it. Follows the standard OpenClaw AGENTS.md format. Useful when multiple agents share a workspace. + +**Edit this when:** you add a new agent, change workspace rules, or update shared resources. + +--- + +### `TOOLS.md` — What the Agent Can Do +Documents tools available to the agent: built-in Claude Code tools, workspace-specific CLIs, MCP servers, and APIs. Also defines restricted actions that require user approval. + +**Edit this when:** you add new tools to the workspace, change permissions, or want to restrict certain actions. + +--- + +### `MEMORY.md` — Long-Term Memory +Accumulates important decisions, context, and learnings across sessions. The agent reads this when starting a new session or recovering context. + +**Edit this when:** you want to manually add context or remove outdated entries. The agent will also write to this file automatically. + +--- + +### `memory/CURRENT_STATE.md` — Right Now +Tracks what's in flight, what's blocked, what was recently finished, and what's planned next. The agent updates this at the end of every session. + +**Edit this when:** you want to manually set the agent's initial task list or correct its understanding of current state. --- ## FAQ **Q: Do I need all these files?** -Start with `SOUL.md`, `IDENTITY.md`, and `memory/CURRENT_STATE.md` — those three give you identity and continuity. Add the rest as your needs grow. +A: `SOUL.md`, `IDENTITY.md`, and `USER.md` are the minimum for a working agent. The others improve reliability and multi-session continuity. -**Q: How does the agent pick up changes to these files?** -The agent reads them at session start. Edit a file and start a new session (or ask the agent to re-read it) for changes to take effect. +**Q: What are the `[PLACEHOLDER]` values?** +A: Bracketed ALL_CAPS values are placeholders you should replace. `` explain what goes there. Search for `[` to find them all. -**Q: Can I use this with a non-OpenClaw Claude Code setup?** -Yes. The files are plain markdown. Point your `CLAUDE.md` at them with `@SOUL.md`, `@IDENTITY.md`, etc., and they work as regular context files. +**Q: Can I have multiple agents in one workspace?** +A: Yes. Add each agent to `AGENTS.md` and give each its own config directory. They'll share the workspace rules but have separate identities and memories. + +**Q: How does the agent remember things between sessions?** +A: It reads `MEMORY.md` and `memory/CURRENT_STATE.md` at the start of each session. For this to work reliably, the agent needs to update `CURRENT_STATE.md` before each session ends. + +**Q: What if the agent seems confused or off-character?** +A: Trigger continuity recovery manually by saying: "Re-read your SOUL.md and IDENTITY.md and re-orient." The agent will follow the recovery protocol defined in `SOUL.md`. + +**Q: Can I add custom tools?** +A: Yes — document them in `TOOLS.md`. For MCP servers, configure them in Claude Code settings and reference them in `TOOLS.md` so the agent knows they exist and how to use them. + +**Q: How do I update the agent's personality?** +A: Edit the `## Vibe` section in `SOUL.md`. Changes take effect in the next session. + +--- + +## Template Version + +`v1.0.0` — Initial release + +--- + +## License + +This template is provided as-is for use with OpenClaw. Modify freely.