AI · 源文件

## 引言

OpenClaw 是一个开源的多智能体框架，它允许你创建多个具有不同角色、模型和权限的 AI 助手（Agent），让它们像团队成员一样协作，完成复杂任务。无论你是想搭建个人助手，还是探索多 Agent 协同工作，OpenClaw 都提供了灵活而强大的配置体系。

本文将从最基础的配置文件开始，带你逐步掌握单 Agent 的配置，再平滑过渡到多 Agent 模式，并深入讲解安全实践、通信机制和高级编排。读完本文，你将能够独立配置一个安全、高效的多智能体系统。

___

## 一、OpenClaw 配置文件体系概览

OpenClaw 的配置采用分层设计，核心文件和目录如下：

|文件/目录|作用|
|---|---|
|~/.openclaw/openclaw.json|**主配置文件**，定义智能体、模型、渠道、工具等核心模块。|
|~/.openclaw/workspace/|默认 Agent 的工作目录，包含记忆文件、技能等。|
|~/.openclaw/agents/<agent-id>/|每个 Agent 的专属配置目录，存放认证信息和会话历史。|
|~/.openclaw/agents/<agent-id>/sessions/|按日期存储的对话记录，独立隔离。|

**理解优先级**（从高到低）：

1. 命令行参数
2. 环境变量
3. Agent 特有配置（agents.list）
4. 全局默认配置（agents.defaults）
5. 内置默认值
6. 

___

## 二、单 Agent 配置详解

单 Agent 模式是最简单的起点，所有配置都集中在 agents.defaults 中。

## 2.1 核心参数

|参数|说明|示例|
|---|---|---|
|workspace|Agent 工作目录，存放记忆、文件等。|"C:\\\\Users\\\\username\\\\.openclaw\\\\workspace"|
|model.primary|主模型 ID，格式 提供商/模型ID。|"dashscope/kimi-k2.5"|
|temperature|控制输出随机性，0.2~0.5 较省 token。|0.3|
|compaction|上下文压缩策略，避免超出窗口。|{ "reserveTokensFloor": 20000, "memoryFlush": { "enabled": true } }|
|heartbeat|空闲重置时间，防止长期占用 token。|{ "every": "30m" }|
|memorySearch|记忆搜索开关，学习阶段建议禁用。|{ "enabled": false }|
|skills|工具权限白名单。|{ "allow": \["file.read", "browser.navigate"\] }|

## 2.2 完整单 Agent 配置示例

```
{
 "agents": {
 "defaults": {
 "workspace": "C:\\Users\\longx\\.openclaw\\workspace",
 "model": {
 "primary": "dashscope/kimi-k2.5"
 },
 "temperature": 0.3,
 "compaction": {
 "reserveTokensFloor": 20000,
 "memoryFlush": { "enabled": true }
 },
 "heartbeat": { "every": "30m" },
 "memorySearch": { "enabled": false },
 "skills": {
 "allow": ["file.read", "browser.navigate"]
 }
 }
 },
 "models": {
 "mode": "merge",
 "providers": {
 "dashscope": {
 "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
 "api": "openai-completions",
 "models": [
 {
 "id": "kimi-k2.5",
 "name": "Kimi K2.5",
 "contextWindow": 256000,
 "maxTokens": 8192
 }
 ]
 }
 }
 },
 "gateway": {
 "port": 18789,
 "mode": "local",
 "bind": "loopback",
 "auth": {
 "mode": "token",
 "token": "32位随机字符串"
 }
 }
}
```

## 2.3 个性化文件：让 Agent 拥有“人格”

在工作目录中，你可以创建以下文件来定制 Agent 的行为：

- **SOUL.md**：定义 Agent 的核心人格和职责，每次对话都会读取。
- \# 你是一位耐心、细致的学习助手 - 帮助用户理解技术概念。 - 先给结论，再展开细节。
- **MEMORY.md**：Agent 自动更新的长期记忆，也可手动编辑。
- **USER.md**：存储特定用户的信息，用于个性化回应。
- 

___

## 三、单 Agent 安全实践

安全是配置的重中之重，请务必落实以下措施：

1. **工具权限最小化**
2. 用 skills.allow 白名单，只开启必需工具。
3. 高危工具（如 shell.execute）除非必要，否则绝不开启。
4. 
5. **网关安全**
6. gateway.bind: "loopback" 确保服务仅本地访问。
7. 认证令牌至少 32 位随机字符，避免简单密码。
8. 
9. **定期审计**
10. 运行 openclaw security audit --deep 检查风险。
11. 及时删除来源不明的第三方技能。
12. 

___

## 四、从单 Agent 迈向多 Agent

当你熟悉单 Agent 后，可以开始构建多 Agent 团队。

## 4.1 为什么需要多 Agent？

- **角色分离**：写作助手和代码助手各司其职。
- **任务并行**：同时处理多个独立任务。
- **专业分工**：不同模型发挥各自优势。
- **复杂流程**：主 Agent 分解任务，子 Agent 并行执行。
- 

## 4.2 多 Agent 核心配置：agents.list

在 agents 下添加 list 数组，每个 Agent 独立配置：

```
"agents": {
 "defaults": { ... },
 "list": [
 {
 "id": "writer",
 "name": "写作助手",
 "workspace": "C:\\Users\\longx\\.openclaw\\workspace-writer",
 "model": { "primary": "dashscope/kimi-k2.5" },
 "skills": { "allow": ["file.write"] }
 },
 {
 "id": "coder",
 "name": "代码助手",
 "workspace": "C:\\Users\\longx\\.openclaw\\workspace-coder",
 "model": { "primary": "deepseek/deepseek-coder" },
 "skills": { "allow": ["shell.execute"] }
 }
 ]
}
```

**关键点**：

- 每个 Agent 必须有**独立的工作区**，避免文件冲突。
- 可覆盖全局的 model 和 skills，实现精细控制。
- id 是唯一标识，用于路由和通信。
- 

## 4.3 个性化独立

为每个 Agent 在其工作区创建独立的 SOUL.md，赋予不同人格。例如 writer 侧重文采，coder 侧重代码。

___

## 五、多 Agent 通信：agentToAgent

Agent 之间可以互相发送消息，实现协作。

## 5.1 配置通信

```
"tools": {
 "agentToAgent": {
 "enabled": true,
 "allow": ["writer", "coder"] // 允许这两个 Agent 互相通信
 }
}
```

allow 列表中的 Agent 可以主动向其他 Agent 发送消息。

## 5.2 通信方式

在对话中，Agent 可以使用 @目标ID 直接向另一个 Agent 发送请求。例如：

用户对 writer 说：“请写一篇技术文章，需要代码示例，让 @coder 提供代码。”

writer 会先规划文章大纲，然后内部请求 coder 生成代码，最后整合回复用户。整个过程对用户透明。

## 5.3 查看通信日志

通过 openclaw sessions list --agent <id> 可以查看每个 Agent 的会话历史，包括内部消息。

___

## 六、高级编排：subagents

OpenClaw 支持编排器模式：一个主 Agent 动态创建子 Agent 来执行子任务。

## 6.1 配置示例

```
"agents": {
 "defaults": {
 "subagents": {
 "maxSpawnDepth": 2,
 "maxChildrenPerAgent": 5,
 "maxConcurrent": 8,
 "model": "dashscope/kimi-k2.5",
 "thinking": "low"
 }
 }
}
```

- maxSpawnDepth：子 Agent 可继续创建子 Agent 的深度。
- maxChildrenPerAgent：单个 Agent 最多同时拥有的子 Agent 数量。
- maxConcurrent：全局并发子 Agent 上限。
- model：子 Agent 默认模型。
- thinking：子 Agent 的思考强度（影响 token 消耗）。
- 

## 6.2 工作流程

1. 主 Agent 收到复杂任务。
2. 主 Agent 分解任务，为每个子任务创建子 Agent（可指定不同模型）。
3. 子 Agent 并行执行，返回结果。
4. 主 Agent 汇总，生成最终回复。
5. 

这种模式适合处理需要多领域知识的复杂问题。

___

## 七、多 Agent 安全考虑

多 Agent 引入更多通信路径，安全措施需要升级：

- **工作区隔离**：每个 Agent 必须独立工作区，防止恶意操作扩散。
- **通信白名单**：agentToAgent.allow 只列出必要的 Agent，不要全部放行。
- **权限最小化**：每个 Agent 只开启必需的技能，特别是高危工具。
- **定期审计**：运行 openclaw security audit --deep，检查是否有权限过大或异常通信。
- 

___

## 八、常用管理命令

|命令|作用|
|---|---|
|openclaw gateway start|启动网关（必须）。|
|openclaw agents list|查看所有 Agent 状态。|
|openclaw msg --agent <id> "消息"|向指定 Agent 发送消息。|
|openclaw sessions list --agent <id>|查看 Agent 的会话列表。|
|openclaw agentToAgent status|查看通信状态。|
|openclaw doctor --fix|自动检查和修复配置问题。|
|openclaw security audit --deep|深度安全审计。|

___

## 九、实战：写作助手与代码助手协作

1. 按照前文配置 writer 和 coder。
2. 确保通信已开启。
3. 向 writer 发送任务：“我想写一篇关于贪吃蛇游戏的技术文章，需要 Python 代码。请先写大纲，然后让 @coder 提供完整代码。”
4. writer 规划大纲，向 coder 请求代码，coder 返回代码，writer 整合后回复。
5. 通过 openclaw sessions list --agent writer 查看整个对话过程。
6. 

___

## 十、总结

从单 Agent 到多 Agent，OpenClaw 提供了一个灵活而强大的配置框架。关键在于理解配置分层、掌握核心参数、落实安全措施，并逐步引入角色分工和通信机制。希望本文能帮助你搭建属于自己的 AI 智能体团队，开启高效协作之旅。

如果你在配置中遇到任何问题，欢迎查阅官方文档或在社区交流。动手实践是最好的学习方式，现在就开始吧！

___

> 本文为原创技术教程，基于 OpenClaw 2026.2.26 版本撰写。配置示例仅供参考，请根据实际情况调整。