🤖

OpenClaw Agents 配置完整指南

从零开始，手把手教你配置和管理隔离的 Agent 实例

📑 目录

🤖 什么是 Agent？

Agent 是 OpenClaw 中隔离的助手实例。每个 Agent 可以独立配置：

  • 独立的工作区 — 独立的 skills、文档、记忆文件
  • 独立的身份 — 名字、头像、emoji、性格定义
  • 独立的聊天渠道 — 绑定不同的 Telegram/WhatsApp/Discord 账号
  • 独立的模型配置 — 使用不同的 AI 模型
💡 类比理解 可以把 Agent 理解为「手机上的应用多开」—— 同一个应用，但每个实例有独立的账号和数据。

🤔 为什么需要多个 Agent？

场景 单 Agent 多 Agent
个人使用 ✅ 足够 ⚪ 可选
工作/生活分离 ❌ 混乱 ✅ 清晰隔离
多项目管理 ❌ 记忆混杂 ✅ 项目独立
团队协作 ❌ 权限难控 ✅ 每人一个
测试/开发 ❌ 风险高 ✅ 安全隔离

📋 配置方法总览

方法 难度 适用场景 推荐度
交互式添加 简单 新手、快速配置 ⭐⭐⭐⭐⭐
命令行配置 中等 批量配置、脚本化 ⭐⭐⭐⭐
配置文件 较难 高级定制、迁移备份 ⭐⭐⭐

🎯 方法一：交互式添加（推荐新手）

✨ 为什么推荐这个方法？

  • 有向导引导，不容易出错
  • 自动处理默认值
  • 适合不熟悉命令的用户

📝 详细步骤

1 运行添加命令 
openclaw agents add 代理名字

例如：

openclaw agents add work-assistant
openclaw agents add personal
2 跟随向导设置

系统会提示你输入：

  • 工作区目录路径
  • 绑定的聊天渠道
  • 使用的模型
  • 其他配置选项
3 确认配置

检查显示的配置摘要，确认无误后完成。

⚠️ 注意 如果终端没有显示交互提示，可能需要添加 --non-interactive 参数并手动提供所有必需选项。

⚡ 方法二：命令行配置（高级）

🎯 适用场景

  • 批量创建多个 Agent
  • 脚本自动化部署
  • 精确控制每个参数

📝 详细步骤

1 运行添加命令（带参数） 
openclaw agents add my-assistant \
  --workspace ~/.openclaw/workspace \
  --agent-dir ~/.openclaw/agents/my-assistant \
  --model qwen-portal/qwen3.5-plus \
  --bind telegram:my-bot-account
2 参数说明
参数 说明 必需？
name Agent 名字 必需
--workspace <dir> 工作区目录（放 skills、文档等） 推荐
--agent-dir <dir> Agent 状态目录（存储配置、记忆等） 可选
--model <id> 使用的模型 ID 可选
--bind <channel:account> 绑定的聊天渠道（可重复） 可选
--non-interactive 禁用交互提示 可选
--json 输出 JSON 摘要 可选
3 验证创建成功 
openclaw agents list
💡 小技巧 --bind 参数可以重复使用，绑定多个渠道： 
--bind telegram:bot1 --bind whatsapp:account1

📄 方法三：配置文件（底层）

🎯 适用场景

  • 手动修改已有配置
  • 批量迁移 Agent 配置
  • 备份和恢复
  • 高级定制

📝 配置文件位置

~/.openclaw/ ├── config.json # 全局配置 ├── agents/ │ ├── main/ │ │ ├── config.json # 主 Agent 配置 │ │ └── state/ # 状态数据 │ └── my-assistant/ │ ├── config.json # 自定义 Agent 配置 │ └── state/ # 状态数据 └── workspace/ ├── skills/ # 技能目录 ├── SOUL.md # 人格定义 └── MEMORY.md # 长期记忆
⚠️ 警告 直接编辑配置文件前，建议先备份！配置错误可能导致 Agent 无法启动。

📁 目录结构详解

~/.openclaw/ ├── workspace/ # 主工作区 │ ├── skills/ # 技能目录 │ │ ├── weather/ │ │ └── shopify/ │ ├── docs/ # 文档目录 │ ├── memory/ # 记忆文件 │ │ ├── 2026-02-25.md │ │ └── 2026-02-26.md │ ├── SOUL.md # 人格定义 │ ├── USER.md # 用户信息 │ ├── MEMORY.md # 长期记忆 │ ├── AGENTS.md # Agent 说明 │ └── TOOLS.md # 工具配置 │ ├── agents/ # Agents 配置目录 │ ├── main/ # 主 Agent（默认） │ │ ├── config.json # Agent 配置 │ │ ├── state/ # 运行时状态 │ │ └── memory/ # Agent 专属记忆 │ └── work-assistant/ # 工作助手 │ ├── config.json │ ├── state/ │ └── memory/ │ └── config.json # 全局配置

🔧 常用管理命令

操作 命令 说明
📋 列出所有 Agents openclaw agents list 显示已配置的 Agent 列表
📋 JSON 格式列表 openclaw agents list --json 输出 JSON 格式详情
➕ 添加新 Agent openclaw agents add 名字 交互式添加新 Agent
✏️ 修改身份 openclaw agents set-identity 名字 --name "新名字" 修改名字、头像、emoji 等
🗑️ 删除 Agent openclaw agents delete 名字 删除 Agent 及关联数据
🔍 查看帮助 openclaw agents --help 显示完整命令帮助

修改身份示例

# 修改名字和 emoji
openclaw agents set-identity my-assistant \
  --name "小雪" \
  --emoji "❄️"

# 查看可用参数
openclaw agents set-identity --help

🎯 典型使用场景

场景 1：单 Agent（默认配置）

适用人群：个人用户、简单使用

配置：

  • 使用默认的 main Agent
  • 不需要额外配置
  • 直接使用默认工作区 ~/.openclaw/workspace/
✓ 建议 大多数用户只需要一个 Agent，不需要额外配置！

场景 2：工作/生活分离

适用人群：需要区分工作和个人助理的用户

配置：

# 工作助手
openclaw agents add work-assistant \
  --workspace ~/work/openclaw/workspace \
  --bind telegram:work-bot

# 个人助手
openclaw agents add personal \
  --workspace ~/.openclaw/workspace \
  --bind whatsapp:personal

好处：

  • 工作记忆和个人记忆完全隔离
  • 不同的技能配置
  • 不同的聊天渠道

场景 3：多项目管理

适用人群：同时管理多个项目的开发者

配置：

# 项目 A
openclaw agents add project-a \
  --workspace ~/projects/a/openclaw

# 项目 B
openclaw agents add project-b \
  --workspace ~/projects/b/openclaw

好处：

  • 每个项目有独立的技能和记忆
  • 不会混淆项目上下文
  • 方便团队协作

场景 4：测试/开发环境

适用人群：开发新技能或测试配置

配置：

# 使用 dev profile（完全隔离）
openclaw --dev agents add test-agent \
  --workspace ~/test/openclaw
⚠️ 注意 --dev 模式会创建完全隔离的环境，包括独立的端口和配置。

📄 配置文件示例

Agent 配置文件

~/.openclaw/agents/main/config.json

{ "name": "小雪", "emoji": "❄️", "model": "qwen-portal/qwen3.5-plus", "workspace": "~/.openclaw/workspace", "bindings": [ { "channel": "webchat", "accountId": "default" } ], "skills": { "enabled": true, "directories": [ "~/.agents/skills", "~/.openclaw/workspace/skills" ] }, "memory": { "enabled": true, "directory": "~/.openclaw/agents/main/memory" }, "theme": { "color": "#667eea", "avatar": "https://example.com/avatar.png" } }

配置项说明

配置项 说明 默认值
name Agent 显示名字 "Agent"
emoji Agent 表情符号 "🤖"
model 使用的 AI 模型 ID 全局默认模型
workspace 工作区目录路径 "~/.openclaw/workspace"
bindings 绑定的聊天渠道列表 []
skills.enabled 是否启用技能系统 true
skills.directories 技能搜索目录列表 默认两个目录
memory.enabled 是否启用记忆系统 true
theme 主题配置（颜色、头像等） 默认主题

✅ 验证配置

✓ 检查清单
  • Agent 出现在 openclaw agents list 列表中
  • 配置文件存在于正确位置
  • 工作区目录包含必要的文件（SOUL.md、skills 等）
  • Gateway 正常运行
  • 绑定的渠道已登录

🧪 验证步骤

1 检查 Agents 列表 
openclaw agents list
openclaw agents list --json
2 检查 Gateway 状态 
openclaw gateway status
3 检查技能加载

在聊天中问 Agent：

"你现在有哪些技能？"
4 测试渠道绑定

从绑定的渠道（Telegram/WhatsApp 等）发送消息，确认 Agent 能响应。

5 检查配置文件 
# 查看配置文件内容
cat ~/.openclaw/agents/代理名字/config.json

# Windows PowerShell
Get-Content ~/.openclaw/agents/代理名字/config.json

🔧 常见问题排查

❓ 问题 1：Agent 不响应消息

可能原因：

  • Gateway 未运行或已停止
  • 渠道绑定配置错误
  • 渠道未登录或会话过期

解决：

  1. 检查 Gateway 状态：openclaw gateway status
  2. 重启 Gateway：openclaw gateway restart
  3. 检查渠道登录状态
  4. 查看日志：openclaw logs

❓ 问题 2：技能不加载

可能原因：

  • 技能目录配置错误
  • 技能文件夹缺少 SKILL.md
  • Gateway 未重启

解决：

  1. 确认技能在配置的工作区目录内
  2. 确认包含 SKILL.md 文件
  3. 运行：openclaw gateway restart
  4. 检查配置文件中的 skills.directories

❓ 问题 3：配置冲突或覆盖

可能原因：

  • 多个 Agent 使用同一个工作区
  • 配置文件手动修改后格式错误

解决：

  1. 确保每个 Agent 有独立的工作区
  2. 使用 JSON 验证工具检查配置文件格式
  3. 从备份恢复配置文件
  4. 删除冲突的 Agent 重新创建

❓ 问题 4：渠道绑定失败

可能原因：

  • 渠道账号未正确登录
  • 渠道配置格式错误
  • 权限不足

解决：

  1. 使用 openclaw channels 命令检查渠道状态
  2. 重新登录渠道：openclaw channels login
  3. 检查 --bind 参数格式：channel:accountId

❓ 问题 5：删除 Agent 后数据残留

说明：

openclaw agents delete 应该自动清理相关数据，但有时可能需要手动清理。

解决：

# 手动删除残留目录
rm -rf ~/.openclaw/agents/代理名字
rm -rf ~/.openclaw/workspace/代理名字  # 如果工作区也在这个位置
⚠️ 重要提示 修改配置文件后，通常需要重启 Gateway 才能生效： 
openclaw gateway restart

📌 快速参考卡片

操作 命令
列出所有 Agents openclaw agents list
添加新 Agent openclaw agents add 名字
修改身份 openclaw agents set-identity 名字 --name "新名字"
删除 Agent openclaw agents delete 名字
查看帮助 openclaw agents --help
重启 Gateway openclaw gateway restart
检查状态 openclaw gateway status