taodeng/openclaw-agent-template
1
0
Fork 0
mirror of https://github.com/dtzp555-max/openclaw-agent-template.git synced 2026-07-19 09:45:38 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: expand README with full file reference and FAQ

Browse Source 
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
taodeng
2026-03-19 08:00:19 +10:00
co-authored by Claude Sonnet 4.6
parent dab2966565
commit 55185123e3
1 changed files with 123 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+123 -28
View File
@@ -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. `<!-- comments -->` 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.