OpenClaw 添加 Agent 新手指南：从零开始配置多 AI 助手

在 OpenClaw 中，一个 Agent 就是一个独立的 AI 助手，拥有自己的工作空间、人格配置和会话记忆。多个 Agent 可以在同一个 Gateway 中并行运行，互不干扰。

本指南以添加一个名为 ppt 的 Agent 为例，手把手教你完成从创建到验证的完整流程。

什么是 Agent

在 OpenClaw 架构中，每个 Agent 包含三个核心组件：

• Workspace（工作空间） — Agent 的家，包含 AGENTS.md、SOUL.md、USER.md 等配置文件
• State Directory（状态目录） — 存放认证信息、模型配置、会话记录等
• Session Store（会话存储） — 聊天记录，与其他 Agent 完全隔离

多个 Agent 共享同一个 Gateway 进程，但各自独立运行，互不干扰。

添加 Agent 的核心步骤

添加新 Agent 的流程可以概括为四步：创建 Agent → 配置工作空间 → 配置路由绑定（可选）→ 重启并验证。

第一步：创建 Agent

打开终端，执行以下命令：

openclaw agents add ppt --workspace ~/.openclaw/workspace-ppt

参数说明：

• <code>ppt</code> — Agent 的唯一标识（agentId），用于路由和引用
• <code>–workspace</code> — 指定该 Agent 的工作空间路径

注意事项：

• <code>main</code> 是保留名称，不能用作新 Agent 的 id
• 加上 <code>–non-interactive</code> 参数可跳过交互式提示，直接创建

第二步：配置工作空间文件

Agent 创建完成后，在工作空间中创建以下配置文件：

~/.openclaw/workspace-ppt/
├── AGENTS.md      # 操作指令和行为规则
├── SOUL.md        # 人格、语气、边界
├── IDENTITY.md    # Agent 名称、风格、表情
├── USER.md        # 用户信息
├── TOOLS.md       # 本地工具笔记
└── HEARTBEAT.md   # 心跳检查清单（可选）

AGENTS.md 是 Agent 的核心配置文件，定义它应该如何工作。示例：

# AGENTS.md - PPT Agent

## 身份
- 名字：PPT 助手
- 角色：专注于 PPT 内容生成的 AI 助理
- 风格：简洁、专业、结构化

## 行为准则
- 直接高效，不要废话
- 输出结构化的 PPT 大纲和内容
- 所有文档输出到 Obsidian

## 红线
- 禁止删除操作
- 私人信息不外泄

SOUL.md 定义 Agent 的人格和语气，IDENTITY.md 定义标识信息，USER.md 定义用户信息。这些文件的结构与 main Agent 的配置文件一致，只需根据新 Agent 的定位调整内容即可。

第三步：配置路由绑定（可选）

如果你希望通过不同的飞书账号或渠道与不同的 Agent 通信，需要配置路由绑定。

方式 A：使用 CLI 绑定

# 将飞书渠道绑定到 ppt Agent
openclaw agents bind --agent ppt --bind feishu

方式 B：手动编辑配置文件

编辑 <code>~/.openclaw/openclaw.json</code>，添加 <code>agents.list</code> 和 <code>bindings</code> 配置。

如果你只有一个飞书账号，暂时可以不配置绑定。所有消息默认路由到 <code>main</code> Agent。绑定主要用于多账号或多渠道场景。

第四步：重启 Gateway

配置完成后，重启 Gateway 使配置生效：

openclaw gateway restart

第五步：验证

验证新 Agent 是否成功添加：

1. 查看 Agent 列表：<code>openclaw agents list</code>，预期输出应包含 <code>main</code> 和 <code>ppt</code> 两个 Agent
2. 查看绑定关系：<code>openclaw agents list –bindings</code>
3. 检查 Gateway 状态：<code>openclaw gateway status</code>

完整配置示例

以下是 <code>~/.openclaw/openclaw.json</code> 中添加 <code>ppt</code> Agent 后的完整 <code>agents</code> 配置片段：

{
  "agents": {
    "defaults": {
      "workspace": "/Users/jerry/.openclaw/workspace",
      "model": {
        "primary": "qwen/qwen3.5-plus"
      }
    },
    "list": [
      {
        "id": "main",
        "default": true,
        "name": "迈克",
        "workspace": "/Users/jerry/.openclaw/workspace",
        "identity": {
          "name": "迈克",
          "emoji": "🎯"
        }
      },
      {
        "id": "ppt",
        "name": "PPT 助手",
        "workspace": "/Users/jerry/.openclaw/workspace-ppt",
        "model": "qwen/qwen3.5-plus",
        "identity": {
          "name": "PPT 助手",
          "emoji": "📊"
        }
      }
    ]
  }
}

高级配置选项

为 Agent 指定不同模型

每个 Agent 可以独立配置模型：

{
  "id": "ppt",
  "model": "qwen/qwen3-coder-plus"
}

为 Agent 配置技能白名单

限制 Agent 只能使用特定技能：

{
  "id": "ppt",
  "skills": ["obsidian"]
}

为 Agent 配置沙箱

为 Agent 设置独立的沙箱环境：

{
  "id": "ppt",
  "sandbox": {
    "mode": "non-main",
    "scope": "agent",
    "workspaceAccess": "rw"
  }
}

常见问题

如何删除一个 Agent？

openclaw agents delete ppt

<code>main</code> 不能删除。删除操作会将相关文件移到废纸篓，不会硬删除。

如何修改 Agent 的标识信息？

openclaw agents set-identity --agent ppt --name "PPT 助手" --emoji "📊"

工作空间可以共享吗？

可以，但不推荐。共享工作空间会导致配置文件冲突，每个 Agent 应有独立的工作空间。

认证信息是共享的吗？

不共享。每个 Agent 有独立的认证存储目录，例如 <code>~/.openclaw/agents/ppt/agent/auth-profiles.json</code>。

如何查看 Agent 的会话记录？

会话记录存储在 <code>~/.openclaw/agents/<agentId>/sessions/</code> 目录下。

目录结构速查

~/.openclaw/
├── openclaw.json                    # 主配置文件
├── workspace/                       # main Agent 工作空间
│   ├── AGENTS.md
│   ├── SOUL.md
│   ├── IDENTITY.md
│   ├── USER.md
│   ├── TOOLS.md
│   └── memory/
├── workspace-ppt/                   # ppt Agent 工作空间（新建）
│   ├── AGENTS.md
│   ├── SOUL.md
│   ├── IDENTITY.md
│   ├── USER.md
│   ├── TOOLS.md
│   └── memory/
└── agents/
    ├── main/
    │   ├── agent/
    │   └── sessions/
    └── ppt/                         # ppt Agent 状态目录（新建）
        ├── agent/
        └── sessions/

总结

添加一个新 Agent 的核心步骤：

1. <code>openclaw agents add <名称> –workspace <路径></code> — 创建 Agent
2. 在工作空间中编写配置文件（AGENTS.md、SOUL.md 等）
3. （可选）配置路由绑定
4. <code>openclaw gateway restart</code> — 重启生效
5. <code>openclaw agents list</code> — 验证

按照以上步骤，你可以在同一个 OpenClaw 实例中运行多个独立的 AI 助手，每个助手拥有独特的人格、专业领域和会话记忆。