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

参数说明：

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

注意事项：

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

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

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：手动编辑配置文件

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

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

第四步：重启 Gateway

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

openclaw gateway restart

第五步：验证

验证新 Agent 是否成功添加：

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

完整配置示例

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

{
  "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

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

如何修改 Agent 的标识信息？

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

工作空间可以共享吗？

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

认证信息是共享的吗？

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

如何查看 Agent 的会话记录？

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

目录结构速查

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

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