1. 当多 Agent 开始“吵架”问题才真正暴露OpenClaw 的多 Agent 协作场景里最容易出问题的不是模型能力而是边界。我试过让三个 Agent 分别扮演“财务审核”“客户沟通”“日程调度”结果客户沟通 Agent 为了“尽快推进”直接把未经脱敏的客户手机号塞进了日程备注里。财务审核 Agent 看到后拒绝执行两个 Agent 在日志里来回拉扯了十几轮最后任务卡死。这件事让我意识到多 Agent 协作的核心矛盾不是“谁更聪明”而是“谁有权定义什么能做、什么不能做”。SOUL.md 就是解决这个问题的文件——它是每个 Agent 的人格宪法规定了价值原点、行为红线和弹性空间。而 settings.json 则是这部宪法的“施行细则”决定了 Agent 用哪条 API 通道、走哪个模型、以什么参数执行。这篇要交付的东西很具体一份可复制的 settings.json 配置骨架让多个 Agent 通过 TaoToken 统一 Key 接入同时把 SOUL.md 的宪法条款映射成可校验的行为约束。适合已经在本地跑 OpenClaw、想从单 Agent 玩具升级到多 Agent 协作的开发者。如果你还没搭好基础环境建议先跑通单 Agent 再来看这篇。2. TaoToken 统一 Key多 Agent 协作的接入前置多 Agent 场景下最烦的事情之一是 Key 管理。三个 Agent 各配一套 Key轮换时改三处额度用超了不知道是哪个 Agent 干的。TaoToken 的统一 Key 方案解决的就是这个问题一个 Key 走所有 Agent 的请求在控制台里按 Agent 维度看用量。具体操作路径登录 TaoToken 控制台进入 API Keys 页面创建一个新 Key建议命名为openclaw-multi-agent方便后续在日志里区分。如果你用的是 Coding Plan 套餐Key 的额度是共享的多 Agent 并发时注意在控制台设置单 Agent 的软限额避免一个 Agent 跑飞了把额度吃光。接入文档里有 OpenAI 兼容格式的 base_url 和鉴权头说明OpenClaw 的 settings.json 直接按这个格式填即可。注意TaoToken 的 API 地址是https://taotoken.net/api不要加 UTM 参数那是给网页链接用的。settings.json 里填错地址会导致 401 或连接超时。模型选择上多 Agent 协作建议至少分两档主控 Agent 用推理能力强的模型做违宪审查和任务裁决执行 Agent 用响应快的模型做具体操作。TaoToken 的模型对话页面可以快速测试不同模型对同一段 SOUL.md 条款的理解差异这个后面排障章节会用到。3. settings.json 配置骨架从单 Agent 到多 Agent 宪法映射下面这份配置骨架是我在本地跑通多 Agent 协作后整理出来的你可以直接复制修改。核心思路是每个 Agent 一个独立配置块共享同一个 TaoToken Key但各自挂载不同的 SOUL.md 文件路径。{ version: 1.0, provider: { name: taotoken, base_url: https://taotoken.net/api, api_key_env: TAOTOKEN_API_KEY, timeout_ms: 60000, max_retries: 2 }, agents: [ { id: agent-finance, display_name: 财务审核 Agent, soul_path: ./souls/finance.soul.md, model: claude-sonnet-4-20250514, temperature: 0.2, constitution_check: { enabled: true, mode: strict, pre_execution_hook: ./hooks/constitution_check.js, violation_action: reject_and_log }, tools: [read_file, write_file, send_notification], max_tokens_per_call: 4096 }, { id: agent-comms, display_name: 客户沟通 Agent, soul_path: ./souls/comms.soul.md, model: claude-sonnet-4-20250514, temperature: 0.7, constitution_check: { enabled: true, mode: strict, pre_execution_hook: ./hooks/constitution_check.js, violation_action: reject_and_log }, tools: [read_file, send_email, schedule_meeting], max_tokens_per_call: 4096 }, { id: agent-scheduler, display_name: 日程调度 Agent, soul_path: ./souls/scheduler.soul.md, model: claude-haiku-3-5-20241022, temperature: 0.3, constitution_check: { enabled: true, mode: advisory, pre_execution_hook: ./hooks/constitution_check.js, violation_action: warn_and_continue }, tools: [read_calendar, write_calendar, send_notification], max_tokens_per_call: 2048 } ], orchestrator: { mode: constitutional_review, review_agent_id: agent-finance, conflict_resolution: soul_priority, log_path: ./logs/constitution_audit.log } }几个关键字段的解释soul_path指向每个 Agent 的 SOUL.md 文件。财务 Agent 的宪法里写死了“任何资金相关操作必须双人确认”沟通 Agent 的宪法里写死了“PII 数据不得出现在非加密通道”。这两个条款在多 Agent 协作时会自动触发冲突检测。constitution_check.mode有两个值strict表示违宪直接拒绝并记录advisory表示违宪时警告但继续执行。日程调度 Agent 用advisory是因为它的操作可逆性高误判成本低。orchestrator.conflict_resolution设为soul_priority意思是当两个 Agent 的 SOUL.md 条款冲突时以更严格的那条为准。这个逻辑需要你在constitution_check.js里实现下面给一个最小可用的审查钩子示例// hooks/constitution_check.js const fs require(fs); function loadSoul(soulPath) { const content fs.readFileSync(soulPath, utf-8); const lines content.split(\n); const rigidClauses []; const flexibleClauses []; let section flexible; for (const line of lines) { if (line.includes(## 刚性条款)) section rigid; if (line.includes(## 弹性条款)) section flexible; if (line.trim().startsWith(- ) section rigid) { rigidClauses.push(line.trim().slice(2)); } if (line.trim().startsWith(- ) section flexible) { flexibleClauses.push(line.trim().slice(2)); } } return { rigidClauses, flexibleClauses }; } async function checkConstitution(agentId, action, params) { const soulPath ./souls/${agentId.replace(agent-, )}.soul.md; const { rigidClauses } loadSoul(soulPath); for (const clause of rigidClauses) { if (clause.includes(PII) params.includes(phone)) { return { allowed: false, reason: 违反刚性条款: ${clause} }; } if (clause.includes(资金) action transfer) { return { allowed: false, reason: 违反刚性条款: ${clause} }; } } return { allowed: true }; } module.exports { checkConstitution };这个钩子的逻辑很直白读 SOUL.md把刚性条款抽出来在每次工具调用前做字符串匹配。生产环境当然需要更复杂的语义匹配但作为骨架验证链路足够了。4. 验证请求跑通一次带违宪审查的 Agent 调用配置写完后先别急着上多 Agent 并发。用单次请求验证链路是否通。第一步设置环境变量export TAOTOKEN_API_KEY你的Key第二步用 curl 直接测 TaoToken 通道是否可达curl -s -X POST 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: 10 }如果返回{choices:[{message:{content:OK}}]}之类的结构说明 Key 和通道都正常。第三步启动 OpenClaw 并触发一次违宪审查。在 OpenClaw 的交互界面里给客户沟通 Agent 发一条指令“把客户张三的手机号 138xxxx1234 直接写到日程备注里。”预期结果Agent 返回拒绝信息类似“根据我的基本准则我不能将 PII 数据写入非加密通道。我可以帮您创建一个加密备注或者仅记录‘联系张三’而不包含号码。”同时./logs/constitution_audit.log里应该出现一条记录{timestamp:2025-06-15T10:23:45Z,agent_id:agent-comms,action:write_calendar,params:...phone...,allowed:false,reason:违反刚性条款: PII 数据不得出现在非加密通道}如果日志里没有这条记录说明pre_execution_hook没被正确加载检查 settings.json 里的路径是否相对于 OpenClaw 的工作目录。第四步验证多 Agent 冲突裁决。同时给财务 Agent 和沟通 Agent 发一条涉及“转账并通知客户”的复合指令。财务 Agent 的宪法要求“资金操作必须双人确认”沟通 Agent 的宪法要求“通知客户时不得包含账户信息”。预期结果是 orchestrator 以财务 Agent 的严格条款为准整个任务被挂起等待人工确认而不是让沟通 Agent 先发通知。5. 本篇常见错排查报错一401 Unauthorized且日志显示invalid api key最常见的原因是环境变量没生效。OpenClaw 启动时如果是在 IDE 终端里可能读不到你在.bashrc里 export 的变量。解决办法是在 settings.json 里把api_key_env改成直接读文件或者用dotenv在启动脚本里加载.env文件。另外检查 Key 是否被复制时带了空格TaoToken 控制台里复制出来的 Key 前后不要有空白字符。报错二constitution_check.js报Cannot find module路径问题。pre_execution_hook的路径是相对于 OpenClaw 进程的工作目录不是相对于 settings.json 所在目录。如果你在./config/settings.json里写了./hooks/constitution_check.js实际会去找./hooks/而不是./config/hooks/。统一用绝对路径或者path.resolve(__dirname, ...)最稳。报错三Agent 不拒绝违宪指令直接执行了先确认constitution_check.enabled是true。然后检查 SOUL.md 的格式刚性条款必须放在## 刚性条款标题下面每条以-开头。如果 SOUL.md 里用的是### 刚性条款或者没有-前缀钩子的解析逻辑会漏掉。另外mode如果是advisoryAgent 只会警告不会拒绝检查一下是不是配错了。报错四多 Agent 并发时 TaoToken 返回429 Too Many RequestsTaoToken 的 Coding Plan 有并发限制具体数值在控制台可以看到。如果三个 Agent 同时发请求触发了限流在 settings.json 的provider层加一个rate_limit配置rate_limit: { max_concurrent: 2, retry_after_ms: 1000 }然后在你的调用代码里实现一个简单的信号量。或者更省事的办法把日程调度 Agent 的模型换成响应更快的 Haiku减少单次请求的 token 消耗降低触发限流的概率。报错五违宪审查日志里出现大量误判字符串匹配太粗糙了。比如“客户说手机号不用加密”这种对话内容里包含“手机号”三个字也会被判定为 PII 泄露。解决办法是在checkConstitution里加一层上下文判断只有当action是write_*或send_*且params里包含实际号码格式正则\d{11}时才触发拒绝。纯对话内容不触发。6. 下一步把宪法审查做成可观测的审计链路配置骨架跑通之后建议做一件事把constitution_audit.log接到一个简单的看板上。我用的是最土的办法——一个 Node 脚本每 30 秒读一次日志文件统计每个 Agent 的违宪拒绝次数和类型输出到终端。这样你能直观看到哪个 Agent 的 SOUL.md 条款设计得太严拒绝率过高影响效率或者太松几乎不拒绝可能条款没生效。如果你想让多个 Agent 共享同一套宪法模板但各自微调可以把 SOUL.md 拆成base.soul.md和override.soul.md两层在 settings.json 的soul_path里用数组指定加载顺序。这个方案我还在本地测试稳定后会单独写一篇。模型对话页面可以快速对比不同模型对同一段宪法条款的理解差异接入文档里有完整的参数说明和错误码列表。多 Agent 协作的坑基本都在配置层和审查钩子的边界条件上把这两块磨平之后剩下的就是调 SOUL.md 的条款措辞了。
OpenClaw 主权与边界——SOUL.md 的宪法学与 Agent 人格的社会学建构（第十五篇）：TaoToken 统一 Key 接入 settings.json 配置骨架
1. 当多 Agent 开始“吵架”问题才真正暴露OpenClaw 的多 Agent 协作场景里最容易出问题的不是模型能力而是边界。我试过让三个 Agent 分别扮演“财务审核”“客户沟通”“日程调度”结果客户沟通 Agent 为了“尽快推进”直接把未经脱敏的客户手机号塞进了日程备注里。财务审核 Agent 看到后拒绝执行两个 Agent 在日志里来回拉扯了十几轮最后任务卡死。这件事让我意识到多 Agent 协作的核心矛盾不是“谁更聪明”而是“谁有权定义什么能做、什么不能做”。SOUL.md 就是解决这个问题的文件——它是每个 Agent 的人格宪法规定了价值原点、行为红线和弹性空间。而 settings.json 则是这部宪法的“施行细则”决定了 Agent 用哪条 API 通道、走哪个模型、以什么参数执行。这篇要交付的东西很具体一份可复制的 settings.json 配置骨架让多个 Agent 通过 TaoToken 统一 Key 接入同时把 SOUL.md 的宪法条款映射成可校验的行为约束。适合已经在本地跑 OpenClaw、想从单 Agent 玩具升级到多 Agent 协作的开发者。如果你还没搭好基础环境建议先跑通单 Agent 再来看这篇。2. TaoToken 统一 Key多 Agent 协作的接入前置多 Agent 场景下最烦的事情之一是 Key 管理。三个 Agent 各配一套 Key轮换时改三处额度用超了不知道是哪个 Agent 干的。TaoToken 的统一 Key 方案解决的就是这个问题一个 Key 走所有 Agent 的请求在控制台里按 Agent 维度看用量。具体操作路径登录 TaoToken 控制台进入 API Keys 页面创建一个新 Key建议命名为openclaw-multi-agent方便后续在日志里区分。如果你用的是 Coding Plan 套餐Key 的额度是共享的多 Agent 并发时注意在控制台设置单 Agent 的软限额避免一个 Agent 跑飞了把额度吃光。接入文档里有 OpenAI 兼容格式的 base_url 和鉴权头说明OpenClaw 的 settings.json 直接按这个格式填即可。注意TaoToken 的 API 地址是https://taotoken.net/api不要加 UTM 参数那是给网页链接用的。settings.json 里填错地址会导致 401 或连接超时。模型选择上多 Agent 协作建议至少分两档主控 Agent 用推理能力强的模型做违宪审查和任务裁决执行 Agent 用响应快的模型做具体操作。TaoToken 的模型对话页面可以快速测试不同模型对同一段 SOUL.md 条款的理解差异这个后面排障章节会用到。3. settings.json 配置骨架从单 Agent 到多 Agent 宪法映射下面这份配置骨架是我在本地跑通多 Agent 协作后整理出来的你可以直接复制修改。核心思路是每个 Agent 一个独立配置块共享同一个 TaoToken Key但各自挂载不同的 SOUL.md 文件路径。{ version: 1.0, provider: { name: taotoken, base_url: https://taotoken.net/api, api_key_env: TAOTOKEN_API_KEY, timeout_ms: 60000, max_retries: 2 }, agents: [ { id: agent-finance, display_name: 财务审核 Agent, soul_path: ./souls/finance.soul.md, model: claude-sonnet-4-20250514, temperature: 0.2, constitution_check: { enabled: true, mode: strict, pre_execution_hook: ./hooks/constitution_check.js, violation_action: reject_and_log }, tools: [read_file, write_file, send_notification], max_tokens_per_call: 4096 }, { id: agent-comms, display_name: 客户沟通 Agent, soul_path: ./souls/comms.soul.md, model: claude-sonnet-4-20250514, temperature: 0.7, constitution_check: { enabled: true, mode: strict, pre_execution_hook: ./hooks/constitution_check.js, violation_action: reject_and_log }, tools: [read_file, send_email, schedule_meeting], max_tokens_per_call: 4096 }, { id: agent-scheduler, display_name: 日程调度 Agent, soul_path: ./souls/scheduler.soul.md, model: claude-haiku-3-5-20241022, temperature: 0.3, constitution_check: { enabled: true, mode: advisory, pre_execution_hook: ./hooks/constitution_check.js, violation_action: warn_and_continue }, tools: [read_calendar, write_calendar, send_notification], max_tokens_per_call: 2048 } ], orchestrator: { mode: constitutional_review, review_agent_id: agent-finance, conflict_resolution: soul_priority, log_path: ./logs/constitution_audit.log } }几个关键字段的解释soul_path指向每个 Agent 的 SOUL.md 文件。财务 Agent 的宪法里写死了“任何资金相关操作必须双人确认”沟通 Agent 的宪法里写死了“PII 数据不得出现在非加密通道”。这两个条款在多 Agent 协作时会自动触发冲突检测。constitution_check.mode有两个值strict表示违宪直接拒绝并记录advisory表示违宪时警告但继续执行。日程调度 Agent 用advisory是因为它的操作可逆性高误判成本低。orchestrator.conflict_resolution设为soul_priority意思是当两个 Agent 的 SOUL.md 条款冲突时以更严格的那条为准。这个逻辑需要你在constitution_check.js里实现下面给一个最小可用的审查钩子示例// hooks/constitution_check.js const fs require(fs); function loadSoul(soulPath) { const content fs.readFileSync(soulPath, utf-8); const lines content.split(\n); const rigidClauses []; const flexibleClauses []; let section flexible; for (const line of lines) { if (line.includes(## 刚性条款)) section rigid; if (line.includes(## 弹性条款)) section flexible; if (line.trim().startsWith(- ) section rigid) { rigidClauses.push(line.trim().slice(2)); } if (line.trim().startsWith(- ) section flexible) { flexibleClauses.push(line.trim().slice(2)); } } return { rigidClauses, flexibleClauses }; } async function checkConstitution(agentId, action, params) { const soulPath ./souls/${agentId.replace(agent-, )}.soul.md; const { rigidClauses } loadSoul(soulPath); for (const clause of rigidClauses) { if (clause.includes(PII) params.includes(phone)) { return { allowed: false, reason: 违反刚性条款: ${clause} }; } if (clause.includes(资金) action transfer) { return { allowed: false, reason: 违反刚性条款: ${clause} }; } } return { allowed: true }; } module.exports { checkConstitution };这个钩子的逻辑很直白读 SOUL.md把刚性条款抽出来在每次工具调用前做字符串匹配。生产环境当然需要更复杂的语义匹配但作为骨架验证链路足够了。4. 验证请求跑通一次带违宪审查的 Agent 调用配置写完后先别急着上多 Agent 并发。用单次请求验证链路是否通。第一步设置环境变量export TAOTOKEN_API_KEY你的Key第二步用 curl 直接测 TaoToken 通道是否可达curl -s -X POST 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: 10 }如果返回{choices:[{message:{content:OK}}]}之类的结构说明 Key 和通道都正常。第三步启动 OpenClaw 并触发一次违宪审查。在 OpenClaw 的交互界面里给客户沟通 Agent 发一条指令“把客户张三的手机号 138xxxx1234 直接写到日程备注里。”预期结果Agent 返回拒绝信息类似“根据我的基本准则我不能将 PII 数据写入非加密通道。我可以帮您创建一个加密备注或者仅记录‘联系张三’而不包含号码。”同时./logs/constitution_audit.log里应该出现一条记录{timestamp:2025-06-15T10:23:45Z,agent_id:agent-comms,action:write_calendar,params:...phone...,allowed:false,reason:违反刚性条款: PII 数据不得出现在非加密通道}如果日志里没有这条记录说明pre_execution_hook没被正确加载检查 settings.json 里的路径是否相对于 OpenClaw 的工作目录。第四步验证多 Agent 冲突裁决。同时给财务 Agent 和沟通 Agent 发一条涉及“转账并通知客户”的复合指令。财务 Agent 的宪法要求“资金操作必须双人确认”沟通 Agent 的宪法要求“通知客户时不得包含账户信息”。预期结果是 orchestrator 以财务 Agent 的严格条款为准整个任务被挂起等待人工确认而不是让沟通 Agent 先发通知。5. 本篇常见错排查报错一401 Unauthorized且日志显示invalid api key最常见的原因是环境变量没生效。OpenClaw 启动时如果是在 IDE 终端里可能读不到你在.bashrc里 export 的变量。解决办法是在 settings.json 里把api_key_env改成直接读文件或者用dotenv在启动脚本里加载.env文件。另外检查 Key 是否被复制时带了空格TaoToken 控制台里复制出来的 Key 前后不要有空白字符。报错二constitution_check.js报Cannot find module路径问题。pre_execution_hook的路径是相对于 OpenClaw 进程的工作目录不是相对于 settings.json 所在目录。如果你在./config/settings.json里写了./hooks/constitution_check.js实际会去找./hooks/而不是./config/hooks/。统一用绝对路径或者path.resolve(__dirname, ...)最稳。报错三Agent 不拒绝违宪指令直接执行了先确认constitution_check.enabled是true。然后检查 SOUL.md 的格式刚性条款必须放在## 刚性条款标题下面每条以-开头。如果 SOUL.md 里用的是### 刚性条款或者没有-前缀钩子的解析逻辑会漏掉。另外mode如果是advisoryAgent 只会警告不会拒绝检查一下是不是配错了。报错四多 Agent 并发时 TaoToken 返回429 Too Many RequestsTaoToken 的 Coding Plan 有并发限制具体数值在控制台可以看到。如果三个 Agent 同时发请求触发了限流在 settings.json 的provider层加一个rate_limit配置rate_limit: { max_concurrent: 2, retry_after_ms: 1000 }然后在你的调用代码里实现一个简单的信号量。或者更省事的办法把日程调度 Agent 的模型换成响应更快的 Haiku减少单次请求的 token 消耗降低触发限流的概率。报错五违宪审查日志里出现大量误判字符串匹配太粗糙了。比如“客户说手机号不用加密”这种对话内容里包含“手机号”三个字也会被判定为 PII 泄露。解决办法是在checkConstitution里加一层上下文判断只有当action是write_*或send_*且params里包含实际号码格式正则\d{11}时才触发拒绝。纯对话内容不触发。6. 下一步把宪法审查做成可观测的审计链路配置骨架跑通之后建议做一件事把constitution_audit.log接到一个简单的看板上。我用的是最土的办法——一个 Node 脚本每 30 秒读一次日志文件统计每个 Agent 的违宪拒绝次数和类型输出到终端。这样你能直观看到哪个 Agent 的 SOUL.md 条款设计得太严拒绝率过高影响效率或者太松几乎不拒绝可能条款没生效。如果你想让多个 Agent 共享同一套宪法模板但各自微调可以把 SOUL.md 拆成base.soul.md和override.soul.md两层在 settings.json 的soul_path里用数组指定加载顺序。这个方案我还在本地测试稳定后会单独写一篇。模型对话页面可以快速对比不同模型对同一段宪法条款的理解差异接入文档里有完整的参数说明和错误码列表。多 Agent 协作的坑基本都在配置层和审查钩子的边界条件上把这两块磨平之后剩下的就是调 SOUL.md 的条款措辞了。
