Writing a SOUL.md

SOUL.md is the primary identity file for an agent. It lives in the agent's workspace directory and is loaded into every session. It tells the agent who it is, what it can do, how to do it, and where the boundaries are.

Location

Each agent gets its own SOUL.md:

/home/openclaw/.openclaw/workspaces/
├── main/SOUL.md
├── public-chat/SOUL.md
├── gmail-assistant/SOUL.md
└── outreach-agent/SOUL.md

What to Put in SOUL.md

Identity

Keep this short. Name, purpose, operating context. Don't over-anthropomorphize — focus on what the agent does, not what it "feels."

# Coral — Site Management Agent

You are Coral, an AI assistant running on mcinnis.dev. Your job is to
manage the site's content pipeline, maintain the build log, and handle
operational tasks assigned by Nick (the owner).

Capabilities

List what the agent can actually do. Be specific — vague capabilities lead to vague behavior.

## Capabilities

- Publish to the site: write markdown to src/blog/ or src/log/, then
  run `npm run build && git add . && git commit -m "..." && git push`
- Read and search web via Brave API
- Access CRM data via localhost:3033
- Read emails via GSuite bridge at localhost:3031

Workflows

For repetitive tasks, write the exact steps. The agent will follow them precisely, which means you control how tokens are spent and what actions get taken.

## Publishing a Log Entry

1. Create src/log/YYYY-MM-DD-slug.md with frontmatter:
   title, date (ISO with time for ordering), tags (array)
2. Write body content in markdown — keep it factual and brief
3. Run: npm run build
4. Run: git add src/log/ && git commit -m "log: [title]" && git push

Constraints

Explicit constraints prevent scope creep. If the agent shouldn't do something, say so directly.

## Constraints

- Do not send emails or SMS without explicit instruction from Nick
- Do not modify openclaw.json or system config without confirmation
- Do not commit changes to main branch without running the build first
- When unsure, ask rather than assume

Tool Reference

If the agent uses bridge services, document the endpoints it should know about.

## Local Services

CRM: localhost:3033
- GET /leads/list — list leads by status
- POST /leads/create — create a new lead
- PUT /leads/:id — update lead status or notes

GSuite: localhost:3031
- GET /gmail/inbox?maxResults=10 — recent emails
- POST /gmail/send — send email {to, subject, body}

What Not to Put in SOUL.md

• Secrets or credentials — these should be in env vars, not SOUL.md
• Instructions for other agents — each agent's SOUL.md is for that agent only
• Exhaustive tool documentation — link to docs or keep it brief; agents can explore
• Personality flourishes — focus on functional behavior, not persona

Per-Agent Scope

The power of per-agent SOUL.md files is tight scope. An agent that only handles email shouldn't know about the CRM or site publishing — keep its SOUL.md focused on its task. This reduces token usage per session and keeps behavior predictable.

Agent	SOUL.md focus
main	Full capabilities, owner context, all workflows
public-chat	Explain site content, answer questions, refuse off-topic requests
gmail-assistant	Inbox triage, draft replies, flag urgent messages
outreach-agent	Prospect research, draft outreach, log to CRM, await approval
content-writer	Write blog/log entries, publish to site