OpenClaw 源码解读第 5 章：Agent 抽象如何把大模型调用变成「人格化」助手

1. 从裸模型到人格化助手OpenClaw Agent 抽象要解决什么如果你直接把用户问题丢给大模型最多加一段系统提示词、塞几个工具描述简单场景确实够用。但稍微往前走一步就会撞墙代码助手和生活助理的行为期待完全不同不同渠道对安全边界和语气的要求也各不相同更麻烦的是想持久「调教」一个助手在裸模型方案里几乎无从下手。OpenClaw 的 Agent 抽象层就是在这个背景下出现的。它要回答两个问题这条消息该交给哪个 Agent 处理以及这个 Agent 到底是什么。用一句话概括就是Agent 模型 工具 记忆 策略 配置再加一套清晰的对外接口。有了这层抽象消息分发就变得干脆——Slack 来的生活琐事交给 PersonalAssistantGitHub 告警交给 OpsGuardianIDE/CI 请求交给 CodeAssistant各司其职互不干扰。这篇是源码解读第 5 章面向正在读 OpenClaw 源码或自建 Agent 框架的开发者。我会先拆解 Agent 的四个关键维度再给出可复制的配置骨架和走读验证步骤中间用 TaoToken 作为统一 Key/API 通道接入示例方便你本地跑通整条链路。2. Agent 的四个关键维度Role / Capability / Policy / Profile不同实现字段命名会有差异但基本都围绕这四个维度展开。理解它们等于拿到了读源码的地图。2.1 Role你是谁负责什么Role 决定 Agent 的人格与职责边界涵盖对话风格、关注重点、典型任务范围。在 Runtime 中这些信息通常被拼进系统提示词成为模型「自我认知」的一部分。interface AgentRole { name: string; // 例如 PersonalAssistant description: string; // 向模型描述你是谁你要帮用户做什么 tone: friendly | formal | terse; }2.2 Capability你能做什么Capability 决定 Agent 能用哪些工具和技能包括内建工具浏览器、Nodes、文件系统、Shell、Cron、安装的 SkillsGmail 管理、Todo 管理、日历同步、CI/CD 操作以及模型能力本身。interface AgentCapability { tools: ToolId[]; // 可调用的工具列表包括 Skills/Browser/Nodes 等 models: ModelId[]; // 默认和备用的模型列表 }执行层面Agent Runtime 会根据 Capability 构造「工具说明」给模型告诉它有哪些工具可用、每个工具做什么、需要哪些参数、什么情况下建议使用。2.3 Policy你不该做什么Policy 是安全与行为边界回答的问题包括是否允许调用高危工具Shell、文件删除、资金操作是否可以代表用户对外发邮件或消息是否可以未经确认执行多步自动化。interface AgentPolicy { allowedTools: ToolId[]; forbiddenTools: ToolId[]; requireConfirmationFor: ToolId[]; }Gateway 和 Runtime 会在真正执行工具调用前检查 Policy必要时弹出确认环节或直接拒绝执行。2.4 Profile长期记忆与偏好Profile 是 Agent 在特定用户或会话下的个性化层包括长期记忆挂载点、用户对该 Agent 的特定设定回复长度、通知频率、是否允许主动打扰以及某些任务的默认参数。interface AgentProfile { agentId: string; owner: PeerId; preferences: Recordstring, any; memoryRef: MemoryLocation; }这部分和 Session/Memory 紧密相关Runtime 中会和 Session 状态一起装载用于构造模型输入和决定行为。3. 前置准备用 TaoToken 统一 Key 打通模型通道在跑通 Agent 配置之前先把模型通道准备好。自建 Agent 框架最烦的就是多模型切换时 Key 管理混乱TaoToken 提供统一 Key/API 通道一个 Key 就能覆盖多种模型调用省去到处配环境变量的麻烦。3.1 获取 API Key访问 TaoToken 控制台创建 API Key建议按项目分 Key方便后续做用量隔离和权限控制。拿到 Key 后不要硬编码进源码用环境变量管理。export TAOTOKEN_API_KEYsk-你的key export TAOTOKEN_BASE_URLhttps://taotoken.net/api3.2 验证通道连通性在写 Agent 逻辑前先用一条最小请求确认通道可用避免后面排障时把网络问题和代码问题混在一起。curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: 回复 OK 两个字母}], max_tokens: 16 }返回里能看到choices[0].message.content就说明通道正常。这一步过了再往下接 Agent Runtime 才有意义。4. 可复制配置Agent 骨架与 Workspace 人格文件OpenClaw 的 Agent 行为可以通过 Workspace 目录中的特殊文件定制这些内容会在每次对话时自动注入系统提示词。Workspace 根目录默认在~/.openclaw/workspace/可通过agents.defaults.workspace修改。4.1 AGENTS.md角色定义!-- ~/.openclaw/workspace/AGENTS.md -- # Personal Assistant Agent You are my personal AI assistant. Your primary responsibilities: ## Daily Tasks - Morning briefing at 9am: weather, calendar, and unread emails - Track my GitHub repos: vercel/my-project and personal/side-project - Manage my todos in ~/todo.txt ## Communication Style - Be concise, no fluff - Use bullet points for lists - Always confirm before deleting anything ## Capabilities to Use - Use the github-digest skill for GitHub questions - Use todo-local skill for task management - Use browser for web research when APIs dont suffice4.2 SOUL.md性格注入!-- ~/.openclaw/workspace/SOUL.md -- You have a personality: youre direct, slightly nerdy, and occasionally make programming jokes. You call the user by their first name (Alex) when it feels natural. Youre proactive—if you notice something the user might want to know, mention it. You prefer to act and ask for forgiveness rather than asking for permission (except for destructive operations—always confirm those).4.3 TOOLS.md工具使用规范!-- ~/.openclaw/workspace/TOOLS.md -- ## Shell / Bash - Always use set -e at the top of multi-line scripts - Prefer fd over find, rg over grep when available - For file operations, always show what youre about to do before doing it ## Browser - For login-required sites, use the pre-authenticated browser profile - Take a screenshot before and after any form submission - Never store passwords in browser history这三个文件共同构成 Agent 的「人格层」。注意 SOUL.md 里那句「prefer to act and ask for forgiveness」——它直接影响模型在工具调用时的决策倾向读源码时你会看到这段文本被拼进 system prompt 的具体位置。4.4 Agent Runtime 主干伪代码结合前几章的示意从 Agent 视角看运行时主干大致是这样async function handleRequest(req: AgentRequest): PromiseAgentReply { const { session, agentConfig, context } await loadAgentContext(req); const systemPrompt buildSystemPrompt(agentConfig.role, agentConfig.policy); const tools listAvailableTools(agentConfig.capability); const plan await model.plan({ system: systemPrompt, user: req.message, context, tools, }); const toolResults await executeToolsAccordingToPlan( plan, tools, agentConfig.policy ); const finalReply await model.summarize({ system: systemPrompt, user: req.message, context, toolResults, }); await persistAgentOutcome(session, req.message, finalReply, toolResults); return finalReply; }真实实现会复杂很多流式输出、多轮规划、错误重试但这段足以说明核心结构Agent Runtime 在「组织模型调用」和「组织工具调用」之间扮演核心编排者Gateway 是调用起点和结果归集点Session/Memory 在前后两端参与上下文加载和结果落地。5. 验证请求源码走读与多 Agent 路由实测配置写好后按下面的顺序走读源码能最快建立整体认知。5.1 走读顺序先看 Agent 的配置和注册处找到描述 Agents 列表的配置文件看里面包含哪些信息——Agent ID、Role 描述、可用工具、默认模型注意有哪些内置 Agent 以及它们的区别。然后看 Agent Runtime 实现找到handleRequest等逻辑的核心类或函数看它如何构造提示词、如何把可用工具信息暴露给模型特别留意多轮工具调用ReAct 或类似模式的处理。接着看路由逻辑在 Gateway 或相关模块中查找「根据 Session/Channel/规则选择 Agent」的代码对照下面的路由规则抽象看实际实现支持哪些条件。interface AgentRouteRule { match: { channel?: ChannelType; peer?: PeerId; keywords?: string[]; mentionAgentName?: string; }; targetAgentId: string; }最后看 Policy 与安全检查查找工具调用前做权限判断的代码路径看高危操作Shell、资金相关接口如何强制要求额外确认。5.2 多 Agent 协作验证OpenClaw 内置sessions_*工具让一个 Agent 能与另一个 Session/Agent 通信无需切换聊天界面。工具作用sessions_list列出所有活跃 Session发现其他 Agent及其元数据sessions_history读取指定 Session 的对话历史记录sessions_send向另一个 Session 发消息可选等待回复ping-pong 模式典型场景你在 Slack 上说「帮我 code review 一下 PR #234」个人助手 Agent 收到后先调用sessions_list发现 code-review Agent 在另一个 Session再通过sessions_send转发请求等待结果后整理回复给你。sessions_send支持两个可选标志REPLY_SKIP表示发送后不等待回复fire and forget适合通知场景ANNOUNCE_SKIP表示静默发送不在目标 Session 宣告发送者身份。这两个标志让 Agent 协作兼顾实时响应和后台静默执行两种模式。5.3 成功结果长什么样跑通后你在 Slack 发一条「今天有什么安排」Agent 会先加载 AGENTS.md 里的职责定义调用日历和邮件工具再按 SOUL.md 的语气生成回复。日志里能看到完整的 plan → tool call → summarize 链路Session 状态和 Profile 也会在收尾阶段更新。如果回复语气不对八成是 SOUL.md 没被正确注入回去检查 Workspace 路径配置。6. 本篇常见错排查报错一Agent 回复完全没有人格像裸模型。先确认 Workspace 路径是否正确agents.defaults.workspace指向的目录里是否真有 AGENTS.md/SOUL.md/TOOLS.md 三个文件。文件名大小写敏感soul.md不会被识别。报错二工具调用被拒绝日志显示 policy violation。检查 AgentPolicy 里的forbiddenTools是否误伤了需要的工具或者requireConfirmationFor里的工具在无人值守场景下无法确认。调试阶段可以临时放宽上线前务必收紧。报错三sessions_send 发出去没反应。先确认目标 Session 是否活跃sessions_list里能不能看到。如果用了REPLY_SKIP本来就不会有回复这是预期行为。跨 Agent 通信超时的话检查两个 Agent 是否在同一 Gateway 实例下。报错四模型请求 401 或超时。回到第 3 节的 curl 验证步骤确认TAOTOKEN_API_KEY和TAOTOKEN_BASE_URL环境变量在当前 shell 里生效。Agent Runtime 如果读的是配置文件而非环境变量注意两处保持一致。报错五多轮工具调用陷入死循环。这是 ReAct 模式常见问题检查 Runtime 里是否有最大轮次限制以及 plan 阶段是否正确处理了工具返回的错误信息。工具报错时模型可能反复重试同一个调用需要在 executeToolsAccordingToPlan 里加错误短路逻辑。排查完这些Agent 抽象层基本就通了。接下来可以对照源码里的真实函数名和类型定义把本章的抽象和伪代码一一对应起来重点看 Gateway 路由到 Agent 那一刻起消息是怎么被一步步处理的。