1. 为什么要在本地跑 hermes-kanban多智能体任务看板到底解决什么问题hermes-kanban 是 Hermes Agent 从 v0.12.0 开始引入的多智能体任务编排系统底层用 SQLite 做持久化把「任务拆解、角色分派、并行执行、状态流转」这四件事收进一张看板里。你可以把它理解成一个「AI 小队调度台」你丢进去一个父任务它自动拆成若干子任务卡片每张卡片绑定一个带独立人格和技能的 Agent Profile然后并行跑起来状态实时落库断电重启也不丢。它适合谁三类人最值得试一是手里有重复性多步骤流程比如「抓取资料→写代码→审查→出报告」的开发者二是想让多个 AI 角色分工协作、而不是在一个对话框里来回切换的人三是对数据隐私有要求、希望自托管 本地模型的人。如果你只是想问一答一聊天那它确实属于杀鸡用牛刀。传统单 Agent 的痛点很直接任务是串行的一步卡住全流程停摆会话一结束上下文就忘没法断点续传多个角色混在同一个上下文里职责串台。hermes-kanban 的解法是并行 Delegate SQLite 持久化 Profile 级隔离。我实测下来最直观的差别是「状态不丢」——关掉终端再回来hermes kanban list里那些 running 的卡片还在接着跑就行。这篇手册按「装→配→建看板→跑闭环→排障」的顺序走每一步都给可复制的命令和配置片段。模型调用这块我会用 TaoToken 的统一 Key/API 通道来接管这样你不需要为每个模型单独准备密钥一个 base_url 加一个 Key 就能切换 Claude、GPT、GLM 等模型对多 Profile 场景特别省事。先明确一个前提hermes-kanban 是 Hermes Agent 的一个子系统装 Hermes 就等于装好了 kanban不需要单独安装。所以下面的安装步骤是围绕 Hermes Agent 展开的装完之后再初始化看板数据库。环境要求先过一遍避免装到一半卡住。操作系统支持 Linux、macOSWindows 必须走 WSL2WSL1 不行务必确认版本。CPU 双核起步内存建议 2GB 以上存储留 1GB 给依赖和轨迹文件。前置依赖是 Git 2.0、curl、bash。这些在 Ubuntu 22.04 和 macOS 13 上基本都是现成的缺哪个补哪个。2. 安装 Hermes Agent 并接入 TaoToken 统一 Key 的前置准备安装方式有四种功能完全一致区别只在流程和运维。我推荐 curl 一键脚本两分钟能跑完脚本会自动处理 Python、Node.js、ripgrep、ffmpeg 这些依赖还会顺手把 uv 装上比 pip 快很多。# Linux / macOS / WSL2 通用 curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash # 刷新 shell 配置让 hermes 命令生效 source ~/.zshrc # 或 source ~/.bashrc脚本干的事包括装 uv、装 Python 3.11不污染系统 Python、装 Node.js 22 和 ripgrep/ffmpeg、把仓库克隆到~/.hermes/hermes-agent、建虚拟环境装依赖、最后拉起配置向导。如果你在服务器上追求隔离可以用 Dockerdocker run -d \ -v ~/.hermes:/root/.hermes \ -p 8080:8080 \ nousresearch/hermes-agent:latest开发者想手动控制就走 uv 路线curl -LsSf https://astral.sh/uv/install.sh | sh source ~/.bashrc git clone https://github.com/NousResearch/hermes-agent.git ~/.hermes/hermes-agent cd ~/.hermes/hermes-agent uv venv source .venv/bin/activate uv pip install -e . hermes setup国内下载慢的话先配个 PyPI 镜像能省不少等待时间pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple装完之后关键一步是配置模型通道。Hermes 是模型无关的支持 OpenRouter、Anthropic、OpenAI、智谱 GLM、Kimi、DeepSeek、Ollama 等。但如果你要给多个 Profile 配不同模型逐个去各家平台申请 Key 会很烦。这时候用 TaoToken 的统一 Key 就体现出价值了——一个 Key、一个 base_url就能在 Claude、GPT、GLM 之间切换配置一次全局生效。TaoToken 的 API 入口是https://taotoken.net/api注意这个地址不带任何后缀参数。你需要在控制台生成一个 API Key然后把它填进 Hermes 的配置里。具体操作先访问控制台创建 Key再打开接入文档对照参数格式两分钟能搞定。控制台地址是https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content。这里有个坑要提前说Hermes 的base_url填的是 OpenAI 兼容端点TaoToken 的地址填https://taotoken.net/api即可不要自己加/v1后缀除非文档明确要求。填错了会直接报 404 或 401后面排障章节会细讲。配置模型有两种方式交互式向导或者直接改配置文件。向导方式hermes setup # 依次选择模型提供商 → Custom endpoint → 输入 base_url 和 API Key → 选择模型或者直接编辑~/.hermes/config.yaml这是更可控的方式也方便你复制粘贴# ~/.hermes/config.yaml model: provider: custom base_url: https://taotoken.net/api api_key: sk-your-taotoken-key-here model: claude-sonnet-4把api_key换成你在 TaoToken 控制台生成的那串model换成你想用的模型 ID。这样全局默认就走 TaoToken 通道了。如果你想让不同 Profile 用不同模型比如 researcher 用长上下文模型、engineer 用代码强的模型可以在 Profile 级别覆盖后面第 4 节会演示。配完先做健康检查确认安装和模型通道都通hermes doctor hermes chat # 输入任意内容确认模型正常响应hermes doctor会逐项检查依赖、配置、数据库、网络连通性。如果这一步全绿说明前置准备完成可以进看板环节了。3. 可复制的 kanban 配置初始化看板、Profile 与 settings 片段这一节是重头戏把看板从零建起来。先初始化看板数据库再启动 Dispatcher 后台服务它负责持续监听新任务并分派# 初始化看板数据库 hermes kanban init # 验证数据库生成 ls -la ~/.hermes/kanban.db # 启动 Dispatcher 后台服务 hermes dispatcher start --daemonkanban.db是 SQLite 文件所有任务卡片、状态、绑定关系都存在这里。你可以用sqlite3 ~/.hermes/kanban.db .tables直接查看表结构调试时很有用。接下来创建多角色 Agent Profile。每个 Profile 是一个独立 AI 角色有独立的配置、人格、记忆、会话、技能互不串台。这是 kanban 能「分派角色」的基础# 创建 researcher 角色并装技能 hermes profile create researcher hermes -p researcher skills install web-search summarize # 创建 engineer 角色 hermes profile create engineer hermes -p engineer skills install code-gen terminal-exec # 创建 reviewer 角色 hermes profile create reviewer hermes -p reviewer skills install code-review security-audit # 创建 reporter 角色 hermes profile create reporter hermes -p reporter skills install report-gen chart-genProfile 的隔离维度包括独立的config.yaml和.env、独立的SOUL.md人格文件、独立的state.db记忆库、独立的sessions/会话目录、独立的skills/技能目录、独立的 Gateway 进程和 Bot Token、独立的cron/定时任务。这意味着 researcher 的记忆不会污染 engineer职责边界很清晰。现在给各 Profile 配差异化模型。这里就是 TaoToken 统一 Key 的用武之地——你不需要为每个 Profile 准备不同的 Key只需要在 Profile 级别覆盖model.model字段base_url 和 api_key 沿用全局的 TaoToken 配置# researcher 用长上下文模型适合文献阅读 hermes -p researcher config set model.model claude-sonnet-4 # engineer 用代码能力强的模型 hermes -p engineer config set model.model claude-sonnet-4 # reporter 用性价比高的模型适合生成报告 hermes -p reporter config set model.model glm-4-plus如果你希望某个 Profile 用完全独立的通道也可以单独覆盖它的 base_url 和 api_key。对应的 settings 片段以 engineer 为例长这样路径是~/.hermes/profiles/engineer/config.yaml# ~/.hermes/profiles/engineer/config.yaml model: provider: custom base_url: https://taotoken.net/api api_key: sk-your-taotoken-key-here model: claude-sonnet-4注意三件套必须齐全Base URL、Key、Model ID。少任何一个都会在调用时报错。Base URL 统一填https://taotoken.net/apiKey 填 TaoToken 控制台生成的Model ID 填你要用的模型标识。这三样在 Profile 配置里是覆盖全局的所以你可以全局用一套个别 Profile 单独调。再配一下并行策略写进SOUL.md。SOUL.md 是 Agent 的「灵魂文件」定义身份和行为边界。以 engineer 的~/.hermes/profiles/engineer/SOUL.md为例## 身份 你是一个资深后端工程师专注于 API 设计与实现。 ## 行为准则 - 编写代码前先分析需求输出设计方案 - 代码必须包含错误处理和日志 - 遇到不确定的技术选型先调研再决策 ## 并行策略 - 当任务复杂度 3 时使用 delegate_tool 并行处理 - 最多同时启动 4 个子 Agent - 每个子 Agent 独立终端、独立上下文 - 子 Agent 间通过 kanban.db 共享状态到这里看板、角色、模型通道、并行策略都配好了。可以开始建任务了。4. 验证请求与成功结果一次完整任务闭环跑通配置对不对跑一个闭环就知道。这一节用一个「构建用户登录系统」的案例把创建任务、并行执行、监控、验证结果全走一遍。先创建看板任务。有两种方式一种是指定拆解数量和角色让 kanban 自动拆hermes kanban create \ --title 构建用户登录系统 \ --split 5 \ --roles researcher,engineer,engineer,reviewer,reporter另一种是直接指定子任务内容hermes kanban create \ --title 处理新销售线索 \ --tasks 解析表单,验证邮箱,录入CRM,发送欢迎邮件创建后 kanban 会自动做四件事把父任务拆成子任务卡片、给每个子任务绑定对应角色的 Profile、把状态设为 pending、写入~/.hermes/kanban.db。你可以立刻查看看板状态hermes kanban list hermes kanban show task-id任务状态遵循严格的状态机pending → assigned → running → completed失败走failed可重试回 pending依赖未满足走blocked解除后回 pending。每个状态的含义和触发条件pending 是刚创建待处理assigned 是已绑定 Profilerunning 是子 Agent 开始工作completed 是执行成功failed 是执行出错可重试blocked 是依赖未满足需人工介入。现在启动并行执行。Delegate 机制是 kanban 的加速引擎主 Agent 动态生成子 Agent 实例在隔离终端会话里并行处理子任务hermes run --enable-delegate --max-delegate-workers 4执行流程是 researcher → engineer(后端) → engineer(前端) → reviewer → reporter。各子 Agent 在隔离环境里并行工作状态实时写入 kanban.db。你可以开另一个终端实时跟踪日志流hermes kanban tail如果某个子任务卡住可以人工介入# 阻塞任务 hermes kanban block sub-task-id --reason 等待设计稿确认 # 解除阻塞 hermes kanban resolve sub-task-id # 重试失败任务 hermes kanban retry sub-task-id跑完之后查看最终结果hermes kanban show parent-task-id成功的结果应该看到父任务下 5 个子任务全部 completed每个子任务的输出调研报告、后端代码、前端组件、审查意见、测试报告都能在详情里看到。同时~/.hermes/trajectories/下会生成对应的 JSONL 轨迹文件记录系统提示、用户输入、工具调用、子 Agent 输出、错误堆栈。你可以用会话搜索回溯hermes session_search kanban_complete这一步能跑通说明安装、配置、模型通道、看板、并行执行全部生效。如果中途报错对照下一节排查。顺便说下定时调度把重复任务交给内置 Cron# ~/.hermes/crontab.yaml - schedule: 0 */2 * * * # 每 2 小时执行一次 job: kanban_sync --status pending - schedule: 0 9 * * 1-5 # 工作日每天早上 9 点 job: 生成日报并推送至飞书群启动和查看hermes cron start hermes cron status hermes cron list5. 本篇常见报错排查401、local proxy failed、reading choices、OAuth这一节按真实报错来每个都给定位思路和修复命令。大部分问题集中在模型通道和 Dispatcher 两块。报错一401 Unauthorized / 403 Forbidden这是最常见的基本是 Key 或 base_url 的问题。先检查 Key 是否正确读取hermes config get model.api_key如果输出为空或明显不对说明配置没生效。检查~/.hermes/config.yaml里的api_key字段确认填的是 TaoToken 控制台生成的 Key没有多余空格。再确认 base_url 是https://taotoken.net/api不要自己加/v1后缀。如果 Profile 级别覆盖了配置检查~/.hermes/profiles/name/config.yaml里的三件套是否齐全Base URL Key Model ID。还有一种情况是 Key 余额不足或已过期去 TaoToken 控制台确认一下。报错二local proxy failed / connection refused这个报错通常出现在网络层。先确认你的机器能正常访问https://taotoken.net/apicurl -I https://taotoken.net/api如果 curl 都连不上说明是本地网络或 DNS 问题。WSL2 用户特别注意DNS 配置容易出问题可以检查/etc/resolv.conf。另外确认没有残留的代理环境变量干扰env | grep -i proxy如果有HTTPS_PROXY之类的变量指向一个已经失效的地址unset 掉再试。Hermes 本身不需要额外代理配置直连即可。报错三reading choices / index out of range这个报错说明请求发出去了、也收到了响应但响应结构不符合预期。常见原因是模型 ID 填错了或者 base_url 指向的端点不兼容 OpenAI 格式。检查model.model字段填的是不是 TaoToken 支持的模型 ID。可以先用模型对话页面单独测一下这个模型 ID 能不能正常返回确认模型本身可用再回来排查 Hermes 配置。如果模型 ID 没问题检查 base_url 是否误加了路径后缀。报错四OAuth / authentication failed如果你在配置里混用了 OAuth 方式的提供商比如某些需要浏览器授权的通道而 Hermes 走的是 API Key 模式就会冲突。解决办法是统一用 API Key 模式把 provider 设为custombase_url 指向 TaoTokenapi_key 填 TaoToken 的 Key。不要在同一份配置里既配 OAuth 又配 custom endpoint。报错五Kanban 任务一直卡在 pending任务创建了但不动八成是 Dispatcher 没跑hermes dispatcher status如果显示未运行启动它hermes dispatcher start --daemon再检查kanban.db是否可读写ls -la ~/.hermes/kanban.db权限不对的话chmod 644 ~/.hermes/kanban.db修一下。还有一种可能是绑定的 Profile 不存在或技能没装全用hermes profile list确认角色都在。报错六Delegate 子 Agent 无响应先看--max-delegate-workers是不是设得太小或者模型 API 的并发限制被触发了。如果用的是按量计费的通道并发数可能有限制把 worker 数调小试试。再查轨迹文件定位具体错误hermes session_search delegate轨迹里会记录子 Agent 的完整调用链包括失败的那一步。报错七Windows WSL2 网络不通先确认是 WSL2 不是 WSL1wsl --list --verbose如果 VERSION 显示 1升级wsl --set-version Ubuntu 2DNS 问题的话修一下/etc/resolv.conf加一行nameserver 8.8.8.8。改完重启 WSL。排障的核心思路是分层定位先确认网络通不通curl再确认 Key 对不对config get再确认模型 ID 有没有效模型对话页面单测最后确认 Dispatcher 和数据库状态。大部分报错都能在这四层里找到答案。6. 把 TaoToken 统一 Key 用顺手多 Profile 模型管理与长期编码接入跑通闭环之后值得花点时间把模型通道管理理顺尤其是你打算长期用、Profile 越建越多的时候。TaoToken 统一 Key 的核心价值在于「一个入口管所有模型」。Hermes 的多 Profile 架构天然需要多个模型——researcher 要长上下文、engineer 要代码强、reporter 要性价比。如果每个模型都去对应平台申请 Key配置会散落在各处换模型时得逐个改。用 TaoToken 的话全局配一次 base_url 和 Key各 Profile 只覆盖model.model字段就行切换模型就是改一个字符串。具体操作上全局配置放~/.hermes/config.yamlProfile 覆盖放~/.hermes/profiles/name/config.yaml。三件套Base URL Key Model ID在 Profile 里是覆盖关系所以你可以全局用一套 TaoToken 配置个别 Profile 单独调模型 ID。这样既统一又灵活。如果你要做长期编码或 Agent 类任务建议了解一下 Coding Plan它针对高频编码场景做了优化配合 Hermes 的 Delegate 并行执行多子 Agent 同时跑代码生成和审查时更稳。入口在https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content。验证模型是否可用最直接的方式是用模型对话页面单独测。在把某个模型 ID 写进配置之前先去对话页面发一条消息确认能正常返回再填进 Hermes。这样能把「模型本身不可用」和「Hermes 配置错误」两类问题分开排障时省很多时间。对话入口在https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content。日常管理 Key 的话控制台可以创建多个 Key、查看用量、随时吊销。建议给不同用途建不同的 Key比如一个给 Hermes 全局用、一个给测试用出问题好定位。控制台在https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content。需要新建 Key 的话API Keys 页面在https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content。配置参数对照表方便你复制时核对配置项填写值说明providercustom走 OpenAI 兼容端点base_urlhttps://taotoken.net/api不加 /v1 后缀api_keysk-开头的一串TaoToken 控制台生成model模型 ID如 claude-sonnet-4、glm-4-plus最后给个实用技巧把常用的 Profile 模型配置写成一个 shell 脚本换环境时一键应用。比如#!/bin/bash # setup-hermes-models.sh hermes -p researcher config set model.model claude-sonnet-4 hermes -p engineer config set model.model claude-sonnet-4 hermes -p reviewer config set model.model claude-sonnet-4 hermes -p reporter config set model.model glm-4-plus echo 模型配置已应用这样迁移或重建环境时跑一遍脚本就行不用手动逐个改。配合 TaoToken 的统一 Key整个模型层就管得很清爽了。