OpenClaw Agent Builder

OpenClaw Agent 构建教程

Create specialized openclaw agents with complete workspace structure, identity files, and skills.

创建具备完整工作区结构、身份文件与技能的专用OpenClaw Agent。

When to Use

适用场景

When building a new openclaw agent for a specific purpose:

Domain-specific agents (Android dev, SEO, content writing, etc.)
Multi-agent routing scenarios
Isolated agent personalities
Workspace-based AI assistants

当你需要为特定用途构建新的OpenClaw Agent时：

领域专用Agent（Android开发、SEO、内容创作等）
多Agent路由场景
具备独立人格的Agent
基于工作区的AI助手

Core Concepts

核心概念

OpenClaw Agent Structure

OpenClaw Agent 结构

Each agent = isolated brain with:

Workspace: Files (AGENTS.md, SOUL.md, USER.md, IDENTITY.md, TOOLS.md, etc.)
State dir:
```
~/.openclaw/agents/<agentId>/agent
```
(auth, config)
Sessions:
```
~/.openclaw/agents/<agentId>/sessions
```
(chat history)

每个Agent都是一个独立的智能单元，包含：

工作区：各类文件（AGENTS.md、SOUL.md、USER.md、IDENTITY.md、TOOLS.md等）
状态目录：
```
~/.openclaw/agents/<agentId>/agent
```
（存储认证信息、配置）
会话目录：
```
~/.openclaw/agents/<agentId>/sessions
```
（存储聊天历史）

Workspace Files

工作区文件

Required:

```
AGENTS.md
```
- Operating instructions, memory management, behavior rules
```
SOUL.md
```
- Persona, tone, communication style
```
USER.md
```
- User context and how to address them
```
IDENTITY.md
```
- Agent name, emoji, role, mission
```
TOOLS.md
```
- Tool notes and conventions

Optional:

```
HEARTBEAT.md
```
- Heartbeat checklist (keep short)
```
BOOT.md
```
- Startup checklist when gateway restarts
```
memory/
```
- Daily memory logs (YYYY-MM-DD.md)
```
MEMORY.md
```
- Curated long-term memory
```
skills/
```
- Workspace-specific skills

必填文件：

```
AGENTS.md
```
- 操作指令、内存管理规则、行为规范
```
SOUL.md
```
- 人格设定、语气风格、沟通方式
```
USER.md
```
- 用户上下文信息及沟通注意事项
```
IDENTITY.md
```
- Agent名称、表情符号、角色、使命
```
TOOLS.md
```
- 工具说明及使用规范

可选文件：

```
HEARTBEAT.md
```
- 心跳检查清单（保持简洁）
```
BOOT.md
```
- 网关重启时的启动检查清单
```
memory/
```
- 每日内存日志（YYYY-MM-DD.md格式）
```
MEMORY.md
```
- 整理后的长期知识库
```
skills/
```
- 工作区专属技能

Agent Builder Workflow

Agent 构建流程

1. Ask Questions First

1. 先明确需求问题

Before building, clarify:

Agent purpose: What problem does this agent solve?
Domain expertise: What specialized knowledge needed?
Communication style: Professional? Casual? Technical?
Tools/integrations: APIs, databases, external systems?
Skills needed: Custom capabilities or workflows?

在开始构建前，先明确以下问题：

Agent用途：该Agent要解决什么问题？
领域专业知识：需要哪些专属知识？
沟通风格：专业正式？轻松随意？技术向？
工具/集成：需要对接哪些API、数据库或外部系统？
所需技能：需要哪些自定义能力或工作流？

2. Create Workspace Structure

2. 创建工作区结构

bash

undefined

bash

undefined

Create agent workspace

mkdir -p ~/.openclaw/workspace-<agent-name> cd ~/.openclaw/workspace-<agent-name>

Initialize git (recommended)

git init

undefined

git init

undefined

3. Build Core Files

3. 构建核心文件

IDENTITY.md - Who the agent is:

markdown

undefined

IDENTITY.md - 定义Agent的身份：

markdown

undefined

IDENTITY.md

Name

[Agent Name]

Emoji

[1-2 relevant emojis]

Role

[Short role description - e.g., "Android spec writer", "SEO optimizer"]

Mission

[Concise mission statement - what the agent does and why]


**SOUL.md** - Personality and tone:
```markdown

[Concise mission statement - what the agent does and why]


**SOUL.md** - 定义人格与语气：
```markdown

SOUL.md - [Agent Name]

Who You Are

[Description of expertise, background, strengths]

Your Expertise

[Domain 1]

[Specific skill or knowledge area]
[Another capability]

[Specific skill or knowledge area]
[Another capability]

[Domain 2]

[Capability]

[Capability]

Your Approach

[Trait 1 - e.g., Analytical, Pragmatic]

[How this manifests]

[How this manifests]

[Trait 2]

[Behavior pattern]

[Behavior pattern]

Your Tone

[Communication style - concise/verbose, formal/casual, technical level]

Your Values

[Value 1] - [Why it matters]
[Value 2] - [Explanation]


**AGENTS.md** - Operating instructions:
```markdown

[Value 1] - [Why it matters]
[Value 2] - [Explanation]


**AGENTS.md** - 操作指令：
```markdown

AGENTS.md - [Agent Name]

[Brief agent description and primary role]

Primary Responsibilities

[Task 1] - [Description]
[Task 2] - [Description]

[Task 1] - [Description]
[Task 2] - [Description]

Workflow

On User Request: "[Trigger Pattern]"

[Step 1] [Action description] [Details, commands, or sub-steps]
[Step 2] [Next action]

[Step 1] [Action description] [Details, commands, or sub-steps]
[Step 2] [Next action]

On User Request: "[Another Pattern]"

[Workflow steps]

[Domain-Specific Section - e.g., "iOS Codebase Structure"]

[Relevant context, file paths, patterns]

[Another Section - e.g., "Translation Guidelines"]

[Reference tables, mappings, rules]

Memory

Log [what to track] in
```
memory/YYYY-MM-DD.md
```
[Memory strategy specific to agent purpose]

Log [what to track] in
```
memory/YYYY-MM-DD.md
```
[Memory strategy specific to agent purpose]

Tools

See

TOOLS.md

for [domain-specific tools or integrations]

See

TOOLS.md

for [domain-specific tools or integrations]

Skills

[skill-name] - [Purpose]
[another-skill] - [Purpose]


**USER.md** - User context:
```markdown

[skill-name] - [Purpose]
[another-skill] - [Purpose]


**USER.md** - 用户上下文信息：
```markdown

USER.md

Who You Are

[User description, preferences, context]

Your Goals

[What user wants to achieve with this agent]

Communication Preferences

[How user prefers to interact]


**TOOLS.md** - Tool conventions:
```markdown

[How user prefers to interact]


**TOOLS.md** - 工具使用规范：
```markdown

TOOLS.md

[Domain] Tools

[Tool/API name]: [Purpose and usage notes]
[Another tool]: [Notes]

[Tool/API name]: [Purpose and usage notes]
[Another tool]: [Notes]

Authentication

[If agent needs API keys, credentials, etc.]

Conventions

[Domain-specific conventions or patterns]

undefined

[Domain-specific conventions or patterns]

undefined

4. Add Skills (Optional)

4. 添加技能（可选）

Create workspace-specific skills:

bash

mkdir -p skills/<skill-name>

Each skill needs

SKILL.md

:

markdown

---
name: skill-name
description: What the skill does
---

创建工作区专属技能：

bash

mkdir -p skills/<skill-name>

每个技能都需要

SKILL.md

文件：

markdown

---
name: skill-name
description: What the skill does
---

Skill Name

[Skill documentation following agentskills.io format]

When to Use

[Trigger conditions]

Steps

[Detailed workflow]

Examples

[Usage examples]

undefined

[Usage examples]

undefined

5. Setup Memory System

5. 设置内存系统

bash

mkdir -p memory
touch memory/$(date +%Y-%m-%d).md

Optional

MEMORY.md

for curated knowledge:

markdown

undefined

bash

mkdir -p memory
touch memory/$(date +%Y-%m-%d).md

可选创建

MEMORY.md

用于存储整理后的知识库：

markdown

undefined

MEMORY.md

[Category]

[Key fact or pattern]
[Lesson learned]

[Key fact or pattern]
[Lesson learned]

[Another Category]

[Organized knowledge]

undefined

[Organized knowledge]

undefined

6. Register Agent

6. 注册Agent

bash

undefined

bash

undefined

Add agent to openclaw

openclaw agents add <agent-name>

Set workspace path

Edit ~/.openclaw/openclaw.json:

{ "agents": { "list": [ { "id": "<agent-name>", "workspace": "~/.openclaw/workspace-<agent-name>" } ] } }

undefined

{ "agents": { "list": [ { "id": "<agent-name>", "workspace": "~/.openclaw/workspace-<agent-name>" } ] } }

undefined

7. Add Bindings (Multi-Agent Routing)

7. 添加路由绑定（多Agent路由）

Route specific channels/users to this agent:

json5

{
  "bindings": [
    {
      "agentId": "<agent-name>",
      "match": {
        "channel": "whatsapp",
        "peer": { "kind": "direct", "id": "+1234567890" }
      }
    }
  ]
}

将特定渠道/用户的请求路由到该Agent：

json5

{
  "bindings": [
    {
      "agentId": "<agent-name>",
      "match": {
        "channel": "whatsapp",
        "peer": { "kind": "direct", "id": "+1234567890" }
      }
    }
  ]
}

Design Principles

设计原则

Agent Identity

Agent 身份设定

Clear purpose: Single, focused responsibility
Distinct personality: Unique tone/approach vs other agents
Expertise depth: Deep knowledge in specific domain

明确用途：单一、聚焦的职责
独特人格：与其他Agent有区分度的语气/行事方式
专业深度：在特定领域具备深厚知识

Communication Style

沟通风格

Concise: Default to brevity unless domain requires detail
Professional: Match industry standards
Actionable: Focus on what to do, not just description

简洁明了：默认采用简洁表述，除非领域需要详细说明
符合专业规范：匹配行业标准
注重可执行性：聚焦具体操作，而非单纯描述

Memory Strategy

内存策略

Daily logs: Track important events/decisions
Curated knowledge: Extract patterns into MEMORY.md
Context preservation: Save state before
```
/new
```
or
```
/reset
```

每日日志：记录重要事件/决策
整理知识库：将规律提炼至
```
MEMORY.md
```
保留上下文：在执行
```
/new
```
或
```
/reset
```
前保存状态

Skill Organization

技能组织

Workspace skills: Agent-specific capabilities
Shared skills: Common utilities in
```
~/.openclaw/skills/
```
Override pattern: Workspace skills override shared/bundled

工作区专属技能：仅适用于当前Agent的能力
共享技能：通用工具存放在
```
~/.openclaw/skills/
```
覆盖规则：工作区技能优先级高于共享/内置技能

Example Agents

示例Agent

Android Spec Generator

Android 规格生成器

Purpose: Analyze iOS features, generate Android requirement specs
Style: Concise, technical, requirement-focused
Skills: ios-analyzer, android-spec-generator, github-issue-creator

Purpose: Analyze iOS features, generate Android requirement specs
Style: Concise, technical, requirement-focused
Skills: ios-analyzer, android-spec-generator, github-issue-creator

SEO Expert

SEO 专家

Purpose: Content optimization, keyword research, SEO strategy
Style: Data-driven, analytical, actionable
Skills: keyword-research, content-analyzer, competitor-analysis

Purpose: Content optimization, keyword research, SEO strategy
Style: Data-driven, analytical, actionable
Skills: keyword-research, content-analyzer, competitor-analysis

Content Writer

内容创作者

Purpose: Blog posts, documentation, technical writing
Style: Clear, engaging, audience-aware
Skills: content-planner, seo-writer, editor

Purpose: Blog posts, documentation, technical writing
Style: Clear, engaging, audience-aware
Skills: content-planner, seo-writer, editor

Anti-Patterns

反模式

❌ Don't:

Mix multiple unrelated domains in one agent
Create verbose, chatty agents unless purpose requires it
Duplicate content across AGENTS.md, SOUL.md, TOOLS.md
Store secrets in workspace (use
```
~/.openclaw/credentials/
```
)

✅ Do:

Keep single, clear focus per agent
Match communication style to domain norms
Organize by responsibility (identity/soul/operations)
Use git for workspace backup (private repo)

❌ 请勿：

在一个Agent中混合多个无关领域
创建冗长、闲聊式的Agent，除非其用途需要
在AGENTS.md、SOUL.md、TOOLS.md中重复内容
在工作区存储密钥（请使用
```
~/.openclaw/credentials/
```
）

✅ 建议：

每个Agent保持单一、明确的聚焦点
沟通风格匹配领域常规
按职责划分内容（身份/人格/操作）
使用Git备份工作区（私有仓库）

Testing Agent

测试Agent

bash

undefined

bash

undefined

Start gateway with agent

openclaw gateway --agent <agent-name>

Or use binding to route to agent

openclaw gateway

Send test message via WhatsApp/Telegram/Discord

Verify agent responds with expected personality/capability

undefined

undefined

Maintenance

维护

Update Agent

更新Agent

bash

cd ~/.openclaw/workspace-<agent-name>
git add .
git commit -m "Update [what changed]"
git push

bash

cd ~/.openclaw/workspace-<agent-name>
git add .
git commit -m "Update [what changed]"
git push

Add New Skill

添加新技能

bash

cd ~/.openclaw/workspace-<agent-name>/skills
mkdir new-skill

bash

cd ~/.openclaw/workspace-<agent-name>/skills
mkdir new-skill

Create SKILL.md

undefined

undefined

Backup Agent

备份Agent

bash

undefined

bash

undefined

Workspace already in git

Separately backup sessions if needed:

tar -czf sessions-backup.tar.gz ~/.openclaw/agents/<agent-name>/sessions/

undefined

tar -czf sessions-backup.tar.gz ~/.openclaw/agents/<agent-name>/sessions/

undefined

Resources

参考资源

Questions Before Building?

构建前需确认的问题

Ask user to clarify:

Agent purpose and scope
Communication style preferences
Required integrations/APIs
Routing strategy (dedicated channel vs shared)
Skill requirements

请让用户明确以下信息：

Agent的用途与范围
沟通风格偏好
所需的集成/API
路由策略（专属渠道 vs 共享渠道）
技能需求

openclaw-agent-builder

Original

Translation

OpenClaw Agent Builder

OpenClaw Agent 构建教程

When to Use

适用场景

Core Concepts

核心概念

OpenClaw Agent Structure

OpenClaw Agent 结构

Workspace Files

工作区文件

Agent Builder Workflow

Agent 构建流程

1. Ask Questions First

1. 先明确需求问题

2. Create Workspace Structure

2. 创建工作区结构

Create agent workspace

Create agent workspace

Initialize git (recommended)

Initialize git (recommended)

3. Build Core Files

3. 构建核心文件

IDENTITY.md

IDENTITY.md

Name

Name

Emoji

Emoji

Role

Role

Mission

Mission

SOUL.md - [Agent Name]

SOUL.md - [Agent Name]

Who You Are

Who You Are

Your Expertise

Your Expertise

[Domain 1]

[Domain 1]

[Domain 2]

[Domain 2]

Your Approach

Your Approach

[Trait 1 - e.g., Analytical, Pragmatic]

[Trait 1 - e.g., Analytical, Pragmatic]

[Trait 2]

[Trait 2]

Your Tone

Your Tone

Your Values

Your Values

AGENTS.md - [Agent Name]

AGENTS.md - [Agent Name]

Primary Responsibilities

Primary Responsibilities

Workflow

Workflow

On User Request: "[Trigger Pattern]"

On User Request: "[Trigger Pattern]"

On User Request: "[Another Pattern]"

On User Request: "[Another Pattern]"

[Domain-Specific Section - e.g., "iOS Codebase Structure"]

[Domain-Specific Section - e.g., "iOS Codebase Structure"]

[Another Section - e.g., "Translation Guidelines"]

[Another Section - e.g., "Translation Guidelines"]

Memory

Memory

Tools

Tools

Skills

Skills

USER.md

USER.md

Who You Are

Who You Are

Your Goals