夜雨聆风OpenClaw 多 Agent 架构深度解析：从配置到运行的完整流程
本文深入剖析 OpenClaw 的多 Agent 架构设计，详细讲解从用户发起聊天请求到 Agent 执行响应的完整技术链路，帮助开发者理解其核心原理与配置机制。
一、架构概览
OpenClaw 是一个支持多 Agent 的 AI 助手框架，每个 Agent 可以拥有独立的模型配置、认证信息和会话历史。其核心设计理念是配置隔离与资源独立，让不同用途的 Agent 能够并行运行而互不干扰。
核心特性
- 多 Agent 支持
：可配置多个独立 Agent，每个拥有专属配置 - 认证隔离
：每个 Agent 独立管理 API Key 和 OAuth 凭证 - 会话隔离
：会话历史按 Agent 分离存储 - 模型灵活配置
：支持全局默认 + Agent 级别覆盖 - 环境变量支持
：敏感信息可通过环境变量注入
二、文件存储结构
理解 OpenClaw 的第一步是掌握其文件组织方式。所有数据默认存储在 ~/.openclaw/ 目录下：
关键目录说明
openclaw.json | |
agents/<id>/agent/ | |
agents/<id>/agent/auth-profiles.json | |
agents/<id>/sessions/ | |
agents/<id>/sessions/*.jsonl |
三、配置文件详解
3.1 主配置文件结构
~/.openclaw/openclaw.json 采用 JSON5 格式，支持注释和尾逗号：
{ // Agent 配置 agents: { // 全局默认配置 defaults: { model: { primary: "anthropic/claude-sonnet-4-6", fallbacks: ["openai/gpt-5.4", "google/gemini-3.1-pro"] }, workspace: "~/projects", maxConcurrent: 1, subagents: { maxConcurrent: 1, maxSpawnDepth: 1, model: "anthropic/claude-sonnet-4-6" } }, // Agent 列表 list: [ { id: "main", default: true, name: "主助手", identity: { name: "OpenClaw", emoji: "🤖" }, model: "anthropic/claude-opus-4-6" }, { id: "coder", name: "代码助手", identity: { name: "Coder", emoji: "💻" }, workspace: "~/code-projects", model: "anthropic/claude-sonnet-4-6", skills: ["code", "debug", "refactor"] }, { id: "researcher", name: "研究助手", identity: { name: "Researcher", emoji: "📚" }, model: "openai/gpt-5.4" } ] }, // 模型 Provider 配置 models: { providers: { anthropic: { apiKey: "${ANTHROPIC_API_KEY}", models: [ { id: "claude-opus-4-6", name: "Claude Opus 4.6", contextWindow: 200000 }, { id: "claude-sonnet-4-6", name: "Claude Sonnet 4.6", contextWindow: 200000 } ] }, openai: { apiKey: "${OPENAI_API_KEY}", models: [ { id: "gpt-5.4", name: "GPT-5.4", contextWindow: 128000 } ] }, google: { apiKey: "${GEMINI_API_KEY}", models: [ { id: "gemini-3.1-pro-preview", name: "Gemini 3.1 Pro" } ] } } }, // 认证配置（引用 auth-profiles.json 中的 profile） auth: { profiles: { "anthropic-main": { provider: "anthropic", mode: "api_key" }, "anthropic-oauth": { provider: "anthropic", mode: "oauth", email: "user@example.com" } }, order: { anthropic: ["anthropic-oauth", "anthropic-main"] } }}3.2 Agent 配置字段说明
typeAgentConfig={ id:string;// Agent 唯一标识default?:boolean;// 是否为默认 Agent name?:string;// 显示名称 workspace?:string;// 工作目录 agentDir?:string;// Agent 数据目录（自定义） model?:string|{// 模型配置 primary:string; fallbacks?:string[];}; identity?:{// 个性信息 name?:string; emoji?:string;}; skills?:string[];// 技能白名单 subagents?:{// 子 Agent 配置 allowAgents?:string[]; model?:string;};};3.3 认证配置文件
每个 Agent 的认证信息存储在独立的 auth-profiles.json 中：
路径: ~/.openclaw/agents/coder/agent/auth-profiles.json
{ version: 1, profiles: { "anthropic-coder": { type: "api_key", provider: "anthropic", apiKey: "sk-ant-...", // 加密存储 createdAt: "2025-01-01T00:00:00Z", updatedAt: "2025-03-30T12:00:00Z" }, "openai-coder": { type: "api_key", provider: "openai", apiKey: "sk-...", createdAt: "2025-01-01T00:00:00Z" }, "anthropic-oauth": { type: "oauth", provider: "anthropic", accessToken: "eyJ...", refreshToken: "eyJ...", expiresAt: "2025-04-01T00:00:00Z", email: "user@example.com" } }, usage: { "anthropic-coder": { lastUsedAt: "2025-03-30T12:00:00Z", requestCount: 100 } }}四、完整执行流程
当用户发起聊天请求时，OpenClaw 会经历以下阶段：
流程图
┌─────────────────────────────────────────────────────────────────┐│ 用户发起聊天请求 │└─────────────────────────────────────────────────────────────────┘ │ ▼┌─────────────────────────────────────────────────────────────────┐│ 阶段 1: Gateway 接收请求 ││ ├─ 解析请求参数 (message, sessionKey, agentId) ││ ├─ 验证 agentId 是否存在 ││ └─ 解析 sessionKey 确定 agentId │└─────────────────────────────────────────────────────────────────┘ │ ▼┌─────────────────────────────────────────────────────────────────┐│ 阶段 2: 加载主配置 ││ ├─ 读取 ~/.openclaw/openclaw.json ││ ├─ 解析 JSON5 格式 ││ ├─ 解析 $include 指令 ││ ├─ 解析 ${ENV_VAR} 环境变量引用 ││ └─ 应用默认值 │└─────────────────────────────────────────────────────────────────┘ │ ▼┌─────────────────────────────────────────────────────────────────┐│ 阶段 3: 解析 Agent 配置 ││ ├─ 从 agents.list[] 查找 Agent 定义 ││ ├─ 解析 name, workspace, model, identity ││ └─ 确定 agentDir: ~/.openclaw/agents/<id>/agent │└─────────────────────────────────────────────────────────────────┘ │ ▼┌─────────────────────────────────────────────────────────────────┐│ 阶段 4: 加载 Agent 认证信息 ││ ├─ 读取 ~/.openclaw/agents/<id>/agent/auth-profiles.json ││ ├─ 解析 API Keys / OAuth Tokens ││ └─ 按优先级选择认证方式 │└─────────────────────────────────────────────────────────────────┘ │ ▼┌─────────────────────────────────────────────────────────────────┐│ 阶段 5: 解析模型配置 ││ ├─ Session 覆盖 > Agent 配置 > 全局默认 > 硬编码默认 ││ └─ 返回最终 provider/model │└─────────────────────────────────────────────────────────────────┘ │ ▼┌─────────────────────────────────────────────────────────────────┐│ 阶段 6: 加载会话历史 ││ ├─ 读取 ~/.openclaw/agents/<id>/sessions/sessions.json ││ └─ 加载会话历史 *.jsonl │└─────────────────────────────────────────────────────────────────┘ │ ▼┌─────────────────────────────────────────────────────────────────┐│ 阶段 7: 执行 Agent 运行 ││ ├─ 构建 System Prompt ││ ├─ 调用模型 API ││ ├─ 处理 Tool Calls ││ └─ 返回响应 │└─────────────────────────────────────────────────────────────────┘五、核心源码解析
5.1 配置加载流程
源码位置: src/config/io.ts
functionloadConfig(): OpenClawConfig {// 1. 加载 .env 文件maybeLoadDotEnvForConfig(deps.env);// 2. 读取主配置文件const configPath =resolveConfigPath(deps.env,resolveStateDir(deps.env));const raw = deps.fs.readFileSync(configPath,"utf-8");// 3. 解析 JSON5 格式const parsed = deps.json5.parse(raw);// 4. 解析 $include 指令（支持配置拆分）const resolvedIncludes =resolveConfigIncludesForRead(parsed, configPath, deps);// 5. 解析 ${ENV_VAR} 环境变量引用const resolvedConfig =resolveConfigEnvVars(resolvedIncludes, env);// 6. Schema 验证const validated =validateConfigObjectWithPlugins(resolvedConfig);// 7. 应用运行时默认值const cfg =applyModelDefaults(applyAgentDefaults(applySessionDefaults(validated.config)));return cfg;}5.2 Agent 配置解析
源码位置: src/agents/agent-scope.ts
// 解析 Agent 目录exportfunctionresolveAgentDir(cfg: OpenClawConfig, agentId:string, env){const id =normalizeAgentId(agentId);// 优先使用配置中的 agentDirconst configured =resolveAgentConfig(cfg, id)?.agentDir?.trim();if(configured){returnresolveUserPath(configured, env);}// 默认路径const root =resolveStateDir(env);return path.join(root,"agents", id,"agent");}// 解析 Agent 配置exportfunctionresolveAgentConfig(cfg: OpenClawConfig, agentId:string){const id =normalizeAgentId(agentId);const entry =resolveAgentEntry(cfg, id);return{ name: entry.name, workspace: entry.workspace, model: entry.model, identity: entry.identity, skills: entry.skills, subagents: entry.subagents,};}5.3 认证信息加载
源码位置: src/agents/auth-profiles/paths.ts
// 解析认证存储路径exportfunctionresolveAuthStorePath(agentDir?:string):string{const resolved =resolveUserPath(agentDir ??resolveOpenClawAgentDir());return path.join(resolved,"auth-profiles.json");}认证优先级: src/agents/model-auth.ts
functionresolveProviderApiKey(params:{ cfg: OpenClawConfig; provider:string; agentDir?:string;}):{ apiKey:string; source:string}|null{// 优先级 1: 配置文件中的 SecretRefconst customKey =getCustomProviderApiKey(cfg, provider);if(customKey)return{ apiKey: customKey, source:"models.json"};// 优先级 2: Agent 的 auth-profiles.jsonconst authStore =loadAuthProfileStore(agentDir);const profileKey =resolveApiKeyForProfile(authStore, provider);if(profileKey)return{ apiKey: profileKey, source:"auth-profiles.json"};// 优先级 3: 环境变量const envKey =resolveEnvApiKey(provider);if(envKey)return{ apiKey: envKey.key, source: envKey.source };returnnull;}5.4 模型配置解析
源码位置: src/agents/model-selection.ts
exportfunctionresolveDefaultModelForAgent(params:{ cfg: OpenClawConfig; agentId?:string;}): ModelRef {// 模型解析优先级const agentModelOverride = params.agentId?resolveAgentEffectiveModelPrimary(params.cfg, params.agentId):undefined;// 构建最终配置const cfg = agentModelOverride?{...params.cfg, agents:{...defaults:{ model: agentModelOverride }}}: params.cfg;returnresolveConfiguredModelRef({ cfg, defaultProvider:"anthropic", defaultModel:"claude-opus-4-6"});}六、配置优先级机制
6.1 模型配置优先级
优先级从高到低：1. Session 级别覆盖 └─ 运行时通过参数指定 --model2. Agent 级别配置 └─ agents.list[].model3. 全局默认配置 └─ agents.defaults.model4. 硬编码默认值 └─ anthropic/claude-opus-4-66.2 认证信息优先级
优先级从高到低：1. 配置文件中的 SecretRef └─ models.providers[].apiKey: "${ANTHROPIC_API_KEY}"2. Agent 的 auth-profiles.json └─ ~/.openclaw/agents/<id>/agent/auth-profiles.json3. 环境变量 └─ ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY...4. Shell 环境回退 └─ 从 shell 配置文件读取七、实战配置示例
场景：配置一个代码助手 Agent
步骤 1: 编辑主配置文件
// ~/.openclaw/openclaw.json{ agents: { defaults: { model: "anthropic/claude-sonnet-4-6", workspace: "~/projects" }, list: [ { id: "coder", name: "代码助手", identity: { name: "Coder", emoji: "💻" }, workspace: "~/code-projects", model: "anthropic/claude-sonnet-4-6", skills: ["code", "debug", "refactor", "test"] } ] }}步骤 2: 配置认证信息
# 方式 1: 使用环境变量exportANTHROPIC_API_KEY="sk-ant-..."# 方式 2: 使用 OpenClaw 命令openclaw models auth anthropic --api-key "sk-ant-..."步骤 3: 验证配置
# 列出所有 Agentopenclaw agents list# 查看模型状态openclaw models status# 测试 Agentopenclaw agent --agent-id coder --message"帮我写一个 Python 函数"八、最佳实践
8.1 安全建议
- 使用环境变量
：敏感信息通过 ${ENV_VAR}引用，避免硬编码 - 文件权限
：确保 auth-profiles.json权限为600 - 定期轮换
：定期更新 API Key
8.2 性能优化
- 模型选择
：根据任务复杂度选择合适的模型 - 会话管理
：定期清理旧会话，避免历史过长 - 并发控制
：合理设置 maxConcurrent参数
8.3 多 Agent 协作
{ agents: { list: [ { id: "main", default: true, subagents: { allowAgents: ["coder", "researcher"], // 允许调用子 Agent model: "anthropic/claude-sonnet-4-6" // 子 Agent 默认模型 } }, { id: "coder", skills: ["code", "debug"] }, { id: "researcher", skills: ["search", "summarize"] } ] }}九、总结
OpenClaw 的多 Agent 架构通过以下设计实现了灵活性和隔离性：
| 配置隔离 | |
| 认证隔离 | auth-profiles.json |
| 会话隔离 | |
| 模型灵活 | |
| 安全可控 |
这种架构使得 OpenClaw 能够支持复杂的多 Agent 协作场景，同时保持各 Agent 的独立性和安全性。
参考资料
OpenClaw 官方文档: https://docs.openclaw.ai GitHub 仓库: https://github.com/openclaw/openclaw