1. 为什么单 Agent 跑复杂任务总会“顾此失彼”如果你用 OpenHands 跑过稍微复杂一点的任务大概率遇到过这种情况一开始它思路清晰改了两个文件之后开始重复读同一个文件再往后干脆把前面定好的规范忘了最后交出来的代码风格和项目里其他文件完全对不上。这不是模型不行而是单 Agent 架构在任务复杂度上来之后必然撞上的墙。我试过让一个 Agent 同时处理“读项目结构、写新模块、跑测试、改文档”四件事结果它在第三步就开始丢上下文测试命令跑错目录文档里引用的函数名还是上一版。原因很直接所有信息都塞进同一个上下文窗口工具集越挂越多模型每一步都要在噪声里挑有用信号决策质量自然下滑。有研究给过一组数据当干扰域从 0 增加到 8 个时单 Agent 架构的性能从 0.67 掉到 0.34直接腰斩。OpenHands 给出的解法是 Microagents。你可以把它理解成给主 Agent 配了一排“专项顾问”主 Agent 还是总指挥但遇到 Git 操作、代码审查、某个仓库的私有规范时不用自己硬扛而是把这块交给对应的微代理去处理。微代理本质上是 Markdown 文件加一段 YAML 前导里面写清楚触发条件和知识内容系统在对话中检测到关键词或进入某个仓库时自动加载把对应内容注入上下文。这篇文章聚焦落地配置。我会给出可复制的settings.json骨架讲清楚怎么用 TaoToken 统一 Key 和 API 通道把模型请求接进来然后演示启动后怎么验证 Microagents 真的生效了。适合已经在用 OpenHands、想把手上的多智能体协作跑通的人。2. TaoToken 前置统一 Key 与 API 通道OpenHands 本身不绑定某一家模型服务它通过 LLM 配置去调外部接口。多智能体场景下主 Agent 和各个微代理可能走不同的模型如果每个都单独配 Key、单独管额度维护成本会很高。TaoToken 在这里的作用是提供一个统一的 API 通道你申请一个 Key在 OpenHands 的配置里指向同一个入口主 Agent 和子 Agent 的请求都从这里走。先拿到 Key。打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册后在控制台里创建 API Key。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite Key 管理页面在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。创建完复制出来后面配置里要用。API 的基础地址是 https://taotoken.net/api 注意这个地址不带任何查询参数直接填在 OpenHands 的 base_url 字段里。如果你用的是兼容 OpenAI 接口的客户端把 base_url 设成这个Key 填进去就能通。注意Key 只创建一次就够主 Agent 和微代理共用同一个。不要在每个微代理文件里单独写 Key那样既难维护又容易泄露。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有各语言 SDK 的调用示例配置前可以先扫一眼确认字段名。模型对话的调试入口在 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 配好之后可以先用它验证 Key 是否可用再去跑 OpenHands。3. 可复制配置settings.json 骨架与 Microagents 目录OpenHands 的配置分两块一块是 LLM 连接信息放在settings.json或环境变量里另一块是 Microagents 文件放在仓库的.openhands/microagents/目录下。先看 LLM 配置。{ llm: { model: claude-sonnet-4-20250514, base_url: https://taotoken.net/api, api_key: sk-你的TaoToken密钥, temperature: 0.2, max_output_tokens: 8192 }, agent: { name: CodeActAgent, enable_microagents: true }, microagents: { load_public: true, load_repo: true, repo_path: .openhands/microagents } }几个字段说明一下。base_url固定填 TaoToken 的 API 地址不要加斜杠结尾。api_key填你刚才创建的那串。enable_microagents必须为true否则系统不会去扫描微代理目录。load_public控制是否加载 OpenHands 自带的公共微代理load_repo控制是否加载当前仓库的私有微代理。如果你不想把 Key 写死在文件里用环境变量更稳妥export LLM_API_KEYsk-你的TaoToken密钥 export LLM_BASE_URLhttps://taotoken.net/api export LLM_MODELclaude-sonnet-4-20250514然后在settings.json里把api_key留空OpenHands 会优先读环境变量。接下来建 Microagents 目录。在你的项目根目录下执行mkdir -p .openhands/microagents这个目录下可以放两类文件。一类是repo.md仓库级微代理进入这个仓库就自动生效不需要触发词。另一类是带触发词的知识型微代理比如git.md、testing.md只有对话里出现对应关键词才会被加载。先写一个repo.md把项目的基本规范告诉 Agent--- name: repo-guidelines type: repo --- # 项目规范 ## 技术栈 - Python 3.11使用 uv 管理依赖 - 测试框架 pytest测试文件放在 tests/ 目录 - 代码风格遵循 ruff 默认配置 ## 目录结构 - src/ 放业务代码 - tests/ 放测试 - scripts/ 放运维脚本 ## 提交规范 - commit message 用英文格式为 type(scope): description - 提交前必须跑 ruff check 和 pytest再写一个带触发词的知识型微代理git.md--- name: git-workflow type: knowledge triggers: - git - commit - rebase --- # Git 操作规范 ## 提交 - 每次提交只做一件事不要混合多个不相关的改动 - 提交前用 git diff --staged 确认暂存区内容 ## 分支 - 功能分支从 main 切出命名格式 feature/xxx - 合并前先 rebase main保持线性历史 ## 冲突处理 - 遇到冲突先看 git status 确认冲突文件 - 解决后跑一遍测试再继续 rebase这两个文件放好之后OpenHands 启动时会扫描.openhands/microagents/把repo.md作为常驻上下文注入把git.md注册为关键词触发。当你在对话里提到“帮我 commit 一下”时系统检测到commit这个触发词就把git.md的内容加载进上下文。4. 验证请求确认 Microagents 真的生效配置写完不代表生效得实际验证。启动 OpenHands 后先确认 LLM 通道是通的。用 TaoToken 的模型对话页面发一条测试消息或者在终端里直接 curlcurl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的TaoToken密钥 \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: 回复 ok}] }返回里能看到choices字段就说明 Key 和通道没问题。然后启动 OpenHands进入你的项目目录。启动命令根据你的安装方式不同如果是源码运行cd /path/to/your-project python -m openhands.server启动日志里会有一行关于 microagents 加载的记录类似Loaded 2 microagents from .openhands/microagents。如果没看到这行说明目录路径不对或者enable_microagents没开。进入对话界面后做两个验证动作。第一个验证repo.md是否常驻。直接问 Agent“这个项目用什么测试框架”如果repo.md生效了它会回答 pytest而不是泛泛地说“通常用 unittest 或 pytest”。因为repo.md里明确写了 pytest这个信息在对话开始时就注入了。第二个验证关键词触发。在对话里输入“帮我看看当前 git 状态然后 commit 一下。”如果git.md生效Agent 的回复里会体现你定义的规范比如它会先跑git diff --staged确认暂存区而不是直接git commit -m update。你可以观察它的工具调用序列如果第一步是git status或git diff说明触发词匹配成功微代理内容进了上下文。再进一步你可以故意在对话里不提 git只说“帮我改一下这个函数”然后看 Agent 会不会主动提 commit 规范。正常情况下不会因为触发词没出现git.md没被加载。这个对比能帮你确认触发机制是按预期工作的。5. 本篇常见错排查配置过程中最容易踩的几个坑我按出现频率排一下。Key 填了但请求 401。先检查base_url是不是写成了https://taotoken.net/api/结尾多一个斜杠会导致路径拼接错误。再确认 Key 没有多余空格复制的时候容易带上换行。如果都没问题去控制台看这个 Key 的额度是不是用完了。Microagents 没加载。最常见的原因是目录层级不对。.openhands/microagents/必须在项目根目录下也就是你启动 OpenHands 时所在的那个目录。如果你在子目录里启动系统扫不到。另一个原因是settings.json里enable_microagents写成了false或者漏了这个字段。触发词不生效。检查 YAML 前导里的triggers是不是数组格式每行前面有-。另外触发词匹配是大小写不敏感的但要求是完整单词匹配commit能匹配commit和committing但不会匹配commitment里的部分。如果你写的是中文触发词确认文件编码是 UTF-8。repo.md 和知识型微代理冲突。如果repo.md里写了 Git 规范git.md里也写了两份内容都会进上下文可能导致指令重复。建议repo.md只放仓库级的基础信息具体操作规范放到对应的知识型微代理里按需触发。多智能体委托时子 Agent 拿不到微代理。OpenHands 的委托机制里子 Agent 会继承主 Agent 的事件流和文件存储但微代理的加载是在会话初始化时完成的。如果你在运行中途新增了微代理文件需要重启会话才能生效。另外确认一下子 Agent 的配置里没有单独覆盖microagents相关字段。TaoToken 通道超时。多智能体场景下并发请求会变多如果同时触发多个子 Agent可能遇到超时。可以在settings.json里把timeout调大比如设成 120 秒。另外确认你的 Key 对应的并发额度够用不够的话在控制台升级。6. 长期编码与 Agent 协作的接入建议如果你只是偶尔跑一下 OpenHands上面的配置够用了。但如果你打算把它当成日常编码工具或者要跑多智能体协作的长任务有几个地方值得再优化。第一把微代理文件纳入版本管理。.openhands/microagents/目录跟着仓库走团队成员拉下来就有一致的规范不用每个人单独配。repo.md里写清楚项目的技术栈和目录约定新成员接入时 Agent 直接就能按规范干活。第二主 Agent 和子 Agent 的模型可以分开配。主 Agent 负责规划和调度用推理能力强的模型子 Agent 处理具体子任务可以用响应更快的模型。在 TaoToken 的 Coding Plan 页面 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 可以看到适合长期编码场景的套餐统一 Key 下切换模型不用改配置。第三微代理的触发词要定期清理。项目跑久了triggers列表会越来越长有些词太通用比如test、fix会导致微代理被频繁误触发反而污染上下文。建议每个触发词都对应一个明确的场景宁可少而准不要多而泛。第四如果你用 Claude Code 或类似的 Agent 工具TaoToken 的 Anthropic 兼容通道 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaude_codeutm_campaignrewrite 可以直接对接配置方式和上面类似把 base_url 指向同一个入口就行。配置跑通之后你可以试着把repo.md写得更细一点比如加上“新增 API 必须写对应的测试”“数据库迁移文件命名规则”这类项目特有的约束。微代理的价值就在于把这些隐性知识显性化让 Agent 每次进入项目都能按你团队的规矩来而不是每次都要在对话里重复交代。