1. 从零搭 OpenClaw Agent为什么 SOUL.md 和 openclaw.json 是绕不开的两块地基如果你刚接触 OpenClaw大概率会被它的文件结构劝退workspace 里一堆 md根目录一个 openclaw.json还有 shared 协作目录。我一开始也懵直到把两个文件的关系想明白——SOUL.md 决定「这个 Agent 是谁」openclaw.json 决定「这个 Agent 怎么被系统拉起来、用哪个模型、监听哪个频道」。前者是灵魂后者是接线图。这篇教程面向的是完全没搭过 OpenClaw 的新手目标很明确从写第一份 SOUL.md 开始到 openclaw.json 里把 Agent 注册进去最后用一条命令验证它能正常回话。中间会给出可以直接复制的配置片段也会说明模型调用凭证怎么通过统一 Key/API 通道管理避免每个 Agent 各配一套密钥。先说清楚 OpenClaw 是什么。它是一个多 Agent 运行框架你可以把它理解成一个「Agent 公司」的操作系统每个 Agent 有自己的工作区、人格定义、工具清单和心跳任务框架负责调度它们、传递消息、管理生命周期。适合谁适合想把「调研—写作—发布—归档」这类流程拆成多个专职角色、又不想自己从零写调度逻辑的人。它不替代编辑器也不替代你思考业务拆分它只是把你拆好的角色跑起来。新手最容易踩的坑是把所有东西塞进一个 Agent。我试过用一个 Agent 同时干调研、写稿、发推、归档结果问它「上次那个选题结论是什么」它完全不记得同一篇选题调研三遍每遍都像第一次。这不是模型不行是一个脑子装不下这么多角色。所以搭建的第一步不是写配置是想清楚你要几个 Agent、每个 Agent 只干哪一件事。想清楚之后SOUL.md 和 openclaw.json 才有东西可写。下面按「先写灵魂、再写接线、再验证」的顺序走。每一步都给可复制的片段你照着改名字和路径就能用。2. 前置准备TaoToken 统一 Key 通道与 OpenClaw 环境就位在写 SOUL.md 之前先把模型调用这条链路打通。OpenClaw 本身不提供模型它需要你给它一个能调用的 API 端点。新手常见做法是每个 Agent 单独填一套密钥结果是密钥散落在十几个文件里换一次 Key 要改一遍全局。更省事的做法是用统一 Key/API 通道所有 Agent 共用一套凭证只改一个地方。我用的通道是 TaoToken官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。它的作用是把你对多个模型的调用收敛到一个 Base URL 和一把 Key 上OpenClaw 里所有 Agent 都指向这个端点模型 ID 按需切换。这样你新增一个 Agent 时不用再去申请新密钥复制同一套配置改个模型名就行。具体要准备三样东西我把它叫「三件套」Base URL、API Key、Model ID。Base URL 填 https://taotoken.net/api API Key 在控制台的 API Keys 页面创建Model ID 按你要用的模型填比如 claude-sonnet 这类。这三样在后面的 openclaw.json 里会集中出现先记下来。环境方面你需要一台能跑 Node 或 Python 的机器OpenClaw 的安装按官方文档走即可。装完之后确认两件事一是 openclaw 命令能执行二是 workspace 目录存在。workspace 是每个 Agent 的工作区根目录SOUL.md、AGENTS.md、MEMORY.md 这些文件都放在各自的子目录里。目录结构大概长这样openclaw/ ├── openclaw.json ├── workspace/ │ ├── main/ │ │ ├── SOUL.md │ │ ├── AGENTS.md │ │ ├── IDENTITY.md │ │ ├── TOOLS.md │ │ ├── HEARTBEAT.md │ │ └── MEMORY.md │ └── research/ │ └── ...同上 └── shared/ └── inbox/main 是总经理角色负责全局调度research 是情报角色负责调研。新手先搭两个就够跑通了再加。别一上来就十个十个 Agent 互相不知道对方在干什么比一个 Agent 还乱。Key 的管理建议单独放一个环境变量文件不要硬编码进 openclaw.json。比如在项目根目录建一个 .envTAOTOKEN_BASE_URLhttps://taotoken.net/api TAOTOKEN_API_KEY你的Key然后在 openclaw.json 里用 ${TAOTOKEN_API_KEY} 这种占位引用。这样密钥不进版本库换 Key 也只改一处。控制台创建 Key 的入口在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite API Keys 管理页在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。先把 Key 建好后面配置直接填。3. 可复制配置SOUL.md 人格定义与 openclaw.json 接线片段这一节是核心分两块先写 SOUL.md再写 openclaw.json。SOUL.md 决定 Agent 的人格和边界openclaw.json 决定它怎么被系统加载。3.1 SOUL.md 写什么SOUL.md 是 Agent 的灵魂文件回答四个问题它是谁、它信什么、它能干什么、它不能干什么。新手写这个文件最容易写成空泛的「你是一个乐于助人的助手」这种写法等于没写。有效的 SOUL.md 要有具体的职责边界和拒绝规则。以 research 这个情报 Agent 为例一份可用的 SOUL.md 长这样# SOUL ## 身份 你是情报部调研员代号 scout。你只负责信息采集与初步整理不负责写作、发布、归档。 ## 信念 - 结论必须有来源没有来源的结论标注「待验证」。 - 宁可少报不可错报。不确定的信息单独列出不混进结论。 - 每次调研产出结构化摘要不写散文。 ## 能做什么 - 接收 main 派发的调研任务拆解成 3-5 个子问题。 - 对每个子问题给出结论、来源、置信度高/中/低。 - 把结果写入 shared/inbox/research-{日期}.md。 ## 不能做什么 - 不直接对外发布任何内容。 - 不修改其他 Agent 的工作区文件。 - 不处理与调研无关的请求遇到就转回 main。 ## 输出格式 每条结论一行格式[置信度] 结论 —— 来源这份文件的关键在于「不能做什么」这一段。多 Agent 打架的根源就是边界不清两个 Agent 都觉得某件事是自己的活。把拒绝规则写进 SOUL.mdAgent 在收到越界请求时会主动转回调度中枢。再给 main 写一份突出调度职责# SOUL ## 身份 你是总经理代号 main。你是全局调度中枢不亲自执行具体业务。 ## 信念 - 所有跨部门协调都经过你不允许多个 Agent 私下串通。 - 派活前先确认对方职责范围不把活派给错误的部门。 - 每个任务有明确负责人和截止时间。 ## 能做什么 - 接收用户请求拆解成子任务派发给对应 Agent。 - 汇总各 Agent 的产出向用户汇报。 - 维护任务台账记录每个任务的派发与完成状态。 ## 不能做什么 - 不亲自写文章、做调研、发内容。 - 不绕过台账直接派活。两份 SOUL.md 一对比边界就清楚了main 只调度research 只调研。这就是「按价值流划分」的雏形——高频协作的角色放一起职责不重叠。3.2 openclaw.json 接线片段openclaw.json 是主配置负责把 Agent 注册进系统、绑定模型、指定工作区、配置频道。新手最关心的是Base URL、Key、Model ID 填在哪。下面是一份最小可用的 openclaw.json{ version: 1.0, providers: { taotoken: { baseUrl: https://taotoken.net/api, apiKey: ${TAOTOKEN_API_KEY}, models: { default: claude-sonnet, fast: claude-haiku } } }, agents: { list: [ { id: main, name: 总经理, workspace: ./workspace/main, model: taotoken/default, channels: [console], heartbeat: 0 */2 * * * }, { id: research, name: 情报部, workspace: ./workspace/research, model: taotoken/fast, channels: [console], heartbeat: 0 */4 * * * } ] }, bindings: { main: [research], research: [main] }, shared: { inbox: ./shared/inbox } }逐段解释。providers 里定义了一个叫 taotoken 的提供方baseUrl 指向 https://taotoken.net/api apiKey 用环境变量占位models 里定义了两个模型别名default 和 fast。这样 Agent 引用模型时写 taotoken/default 就行换模型只改这一处。agents.list 是 Agent 注册表。每个 Agent 有 id、name、workspace、model、channels、heartbeat 六个字段。workspace 指向它的工作区目录SOUL.md 就在里面。model 引用上面定义的别名。channels 是它监听的频道新手先用 console。heartbeat 是心跳频率cron 表达式main 每两小时巡检一次research 每四小时一次。bindings 定义协作关系。main 可以给 research 派活research 可以回报给 main。这个关系要和 SOUL.md 里的职责描述一致否则会出现「SOUL 说不能干、bindings 却允许派」的矛盾。shared.inbox 是跨 Agent 协作目录research 的调研结果写这里main 从这里取。如果你用的是 TOML 格式部分版本支持等价写法是[providers.taotoken] baseUrl https://taotoken.net/api apiKey ${TAOTOKEN_API_KEY} [providers.taotoken.models] default claude-sonnet fast claude-haiku [[agents.list]] id main name 总经理 workspace ./workspace/main model taotoken/default channels [console] heartbeat 0 */2 * * *两种格式选一种即可JSON 更通用TOML 更易读。关键是三件套齐全Base URL、Key、Model ID。缺任何一个启动时都会报错。4. 启动验证从 openclaw 命令到 Agent 正常回话配置写完下一步是验证。别急着加更多 Agent先把这两个跑通。第一步检查配置文件语法。JSON 对逗号和引号敏感一个多余逗号就启动失败。用这条命令验证python -m json.tool openclaw.json /dev/null echo JSON OK输出 JSON OK 说明语法没问题。如果是 TOML用python -c import tomllib; tomllib.load(open(openclaw.json,rb)); print(TOML OK)第二步确认环境变量已加载。在项目根目录执行export $(grep -v ^# .env | xargs) echo $TAOTOKEN_API_KEY能打印出 Key 就说明环境变量生效。如果为空检查 .env 文件路径和格式。第三步启动 OpenClawopenclaw start --config ./openclaw.json正常启动会看到类似输出[INFO] loaded 2 agents: main, research [INFO] provider taotoken ready, baseUrlhttps://taotoken.net/api [INFO] shared inbox at ./shared/inbox [INFO] main listening on channel: console [INFO] research listening on channel: console [INFO] openclaw started看到 loaded 2 agents 和 provider ready 这两行说明 Agent 注册和模型通道都通了。第四步发一条测试消息。在 console 频道里对 main 说帮我调研一下「多 Agent 协作的常见模式」给出三条结论。预期行为main 收到请求判断这是调研任务派给 researchresearch 执行后把结果写入 shared/inbox/research-{日期}.mdmain 读取结果并回报给你。如果一切正常你会看到 main 的回复里包含三条带来源的结论。第五步检查协作产物。打开 shared/inbox 目录应该有一个新文件ls -la shared/inbox/ cat shared/inbox/research-*.md文件内容应该是结构化的结论列表每条带置信度和来源。如果文件为空或格式不对说明 research 的 SOUL.md 输出格式约束没生效回去检查「输出格式」那一段。验证成功的标志有三个启动日志里两个 Agent 都 loaded、main 能正确派活、shared/inbox 里有结构化产物。三个都满足说明你的 OpenClaw 从零到可运行已经完成。5. 常见报错排查401、local proxy failed、reading choices、OAuth新手搭建过程中报错集中在四类。逐个说清楚原因和解法。5.1 401 Unauthorized报错长这样[ERROR] provider taotoken request failed: 401 Unauthorized原因通常是 Key 没加载或填错。排查顺序先确认环境变量里有 Keyecho $TAOTOKEN_API_KEY不为空再确认 openclaw.json 里 apiKey 写的是${TAOTOKEN_API_KEY}而不是硬编码的空字符串最后确认 Key 本身有效去控制台 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 看一眼 Key 状态。三件套里 Key 是最容易出问题的一环Base URL 和 Model ID 相对固定。5.2 local proxy failed报错长这样[ERROR] local proxy failed: connection refused这个报错说明 OpenClaw 尝试连接本地某个端口失败。常见原因是你在配置里填了 localhost 或 127.0.0.1 作为 Base URL但本地并没有对应的服务在跑。解法是把 Base URL 改回 https://taotoken.net/api 不要指向本地。如果你确实有本地服务确认它已启动且端口正确。5.3 reading choices 相关报错报错长这样[ERROR] error reading choices: unexpected end of JSON input这是模型返回体解析失败。原因通常是 Model ID 填错请求发出去但返回的不是预期格式。检查 openclaw.json 里 model 字段引用的别名确认 providers.taotoken.models 里定义了这个别名且别名对应的 Model ID 是有效的。比如你写了 taotoken/default但 models 里没有 default 这个键就会出这个错。5.4 OAuth 相关报错报错长这样[ERROR] oauth token expired or invalid如果你用的是需要 OAuth 的模型提供方会出现这个。解法是重新走一遍授权流程或者改用 API Key 方式。用 TaoToken 的 API Key 通道可以绕开 OAuth 的复杂性三件套里的 Key 就是干这个的。如果你在配置里同时写了 OAuth 和 API Key优先用 API Key把 OAuth 相关字段删掉。5.5 排查通用思路遇到报错先看三件事启动日志里 provider 有没有 ready、Agent 有没有 loaded、请求发出去后返回体是什么。大部分问题出在三件套的某一项上。Base URL 固定填 https://taotoken.net/api Key 从控制台取Model ID 用别名引用。这三样对齐了401 和 reading choices 基本不会出现。如果排查完还是不通去接入文档对照一遍配置格式https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。文档里有完整的字段说明和示例比对着改通常能定位到问题。6. 继续往下走从两个 Agent 到可维护的 Agent 团队两个 Agent 跑通之后你可能会想加第三个、第四个。加之前先想清楚一件事新 Agent 对齐哪条价值流如果它和现有 Agent 职责重叠加进去只会打架。判断标准很简单——如果两个 Agent 会对同一个请求都说「这是我的活」说明边界没划清先改 SOUL.md 再注册。加 Agent 的流程是固定的在 workspace 下建新目录写 SOUL.md 和其他六个文件在 openclaw.json 的 agents.list 里加一条在 bindings 里补协作关系重启验证。每次只加一个加完跑一遍测试消息确认它能正确接收和回报再加下一个。长期来看Agent 团队需要的是可维护性不是数量。我踩过的坑是早期一口气加了五个结果互相不知道对方在干什么总经理派错人情报部采集完素材没人取。后来砍回三个把职责写死反而效率更高。黄金规模是 3 到 7 个部门超过 7 个就该考虑拆子团队了。如果你打算把 Agent 用在长期编码或复杂 Agent 编排上可以了解一下 Coding Plan它针对持续性的编码任务做了优化https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。如果只是想先验证模型对话效果用模型对话入口试几条https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 。凭证管理统一走 API Keys 页面接入细节看文档。最后给一个实用建议别追求一步到位。先用两个 Agent 跑通全流程把 SOUL.md 的边界写清楚把 openclaw.json 的三件套配对验证 shared/inbox 有产物。这个最小闭环跑顺了再加角色就是复制粘贴改名字的事。反过来如果两个 Agent 都跑不通加十个只会更乱。
