多智能体系统能不能用来“干正事”差的往往不是模型本身而是两件容易被忽视的事任务中断后怎么不丢活儿外部客户端怎么稳定地找到它。这也是 Hermes 多智能体系列第2集要解决的问题。上一集我们已经把 Hermes 跑起来、让 Agent 能对话但真正要面对生产环境必须补上两个组件Kanban 看板和 Gateway 网关。Kanban 负责把任务从“内存中的临时对话”变成“持久化的工作项”Gateway 则负责把 Agent 和模型、外部工具之间的连接收敛成一个统一入口。这两个组件合在一起才是 Agent 能 7×24 小时待命的基础。这篇文章会重点讲清楚三件事第一Kanban 看板到底解决什么问题怎么配置任务持久化Agent 重启后如何恢复任务第二Gateway 网关怎么配置、怎么理解 token、模型路由和常见 502 报错第三给出一套完整示例从启动 Gateway 到创建看板再到提交任务让一个 Agent 能真正“挂着值班”。文章不会停留在概念层面所有配置和命令都尽量做到可复制、可验证。如果你最近也在研究 Agent 框架或者正把多智能体从 demo 往工程化方向推这篇文章值得读完再收藏。1. 为什么多智能体需要 Kanban 和 Gateway很多人在本地跑通 Agent 对话后第一反应是“就这”——模型能回答问题、能调用一两个工具但一旦关闭终端、切换工作目录或者模型请求超时整个会话上下文就丢了。更麻烦的是当系统里同时存在多个 Agent 时你根本不知道哪个 Agent 该处理下一个任务也不知道上一个任务到底做到哪一步。这里要明确一个判断多智能体系统和单 Agent 对话的本质区别不在模型能力而在工程结构。单 Agent 只要维护一个会话多智能体必须维护一组任务状态、一组连接通道和一组运行规则。没有状态管理Agent 就是“临时工”没有统一网关Agent 就是“封闭办公室”。Kanban 和 Gateway 正好分别解决这两类问题Kanban 看板解决“任务状态”问题。任务创建后进入看板被某个 Agent 领取后变成 in_progress完成后变成 done。哪怕 Agent 进程崩溃、重启、模型调用失败任务记录仍然保存在看板中系统可以从断点恢复。Gateway 网关解决“连接和路由”问题。外部客户端比如对话终端、cc-switch 这类切换工具、其他 Agent不需要各自直连模型服务商而是统一访问 Gateway。Gateway 负责认证、协议转换、模型路由和负载分配。用生活场景类比Kanban 像公司的工单系统任务不会因为处理人下班就消失Gateway 像公司前台外部访客不需要知道每个部门的具体分机号只需跟前台说清楚要找谁。从社区反馈的热词也能看到很多人的实际报错都集中在这两个组件上比如“gateway 未启动 · 请先运行 windows-start.bat 或 mac-start.command”“unexpected status 502 bad gateway”“gateway: not reachable at ws://127.0.0.1:18789”。这说明组件概念不难难的是配置和排错。这也是为什么值得花一整篇文章来拆解。2. Hermes 的核心概念与架构定位在进入配置之前有必要先把 Hermes 里的几个关键概念对齐。社区里有人叫它“爱马仕”有人叫 Hermes Agent其实它并不是一个单体的聊天工具而是一套面向多智能体编排的工程框架。从当前资料看它的能力大致由几个模块组合而成模块作用对应场景Agent任务执行单元处理具体任务调用模型、技能和工具Kanban任务看板持久化任务状态任务排队、状态流转、崩溃恢复Gateway统一网关连接和路由外部客户端接入、模型路由、token 鉴权Skill技能/工具集让 Agent 具备特定领域能力Studio / Desktop管理界面或桌面端查看看板、配置网关、调试 Agent这套结构其实反映了多智能体系统的一个通用设计思路执行、编排、接入三层分离。Agent 层负责“做什么”Kanban 层负责“做到哪一步”Gateway 层负责“谁能调、怎么调”。理解多智能体的四种交互模式也会对配置有帮助。常见分类是串联模式一个 Agent 完成后交给下一个、并行模式多个 Agent 同时处理不同任务、竞争模式多个 Agent 争抢同一任务先完成者获胜、协作模式多个 Agent 共同完成一个复杂任务。在 Hermes 里Kanban 的列设计可以直接支撑串联和并行Gateway 的路由规则则是协作的基础因为不同 Agent 可能需要不同的模型或不同的工具通道。这里要提醒新手一个容易误解的点Agent 不是越多越好Kanban 和 Gateway 也不是为了复杂而复杂。一个任务如果在一个 Agent 的上下文里就能完成就不需要上多智能体编排。只有当任务确实需要拆解、分工、接力、或者跨进程运行时Kanban 的价值才体现出来。否则你只是在给系统增加排队延迟和配置负担。3. 环境准备与前置条件在开始配置之前先把环境准备好。这一节不写死具体版本号因为 Hermes 迭代较快版本以你实际下载的官方包为准但整体思路是通用的。从安装报错信息看Hermes 的本地启动方式很明确Windows 运行windows-start.batmacOS 运行mac-start.command。这通常意味着项目自带一键启动脚本内部会同时拉起 Gateway、看板服务和本地管理服务。建议准备以下环境操作系统Windows 10/11、macOS 或主流 Linux 发行版均可。运行环境看官方要求安装 Node.js 或 Python 环境两个环境同时具备更稳妥。Git用于拉取 Hermes 项目代码或配置仓库。模型 API Key以 DeepSeek 为例准备好 API Key 用于 Gateway 的模型路由配置。本地端口从常见报错看Gateway 默认监听ws://127.0.0.1:18789模型响应服务可能涉及127.0.0.1:15721注意这些端口不能被占用。一个比较稳妥的做法是先做端口检查# Windows netstat -ano | findstr 18789 15721 # macOS / Linux lsof -i :18789 lsof -i :15721如果端口被占用优先排查是否已经有旧的 Hermes 进程在运行或者被其他本地服务占用。这里也建议不要用管理员或 root 身份运行 Hermes普通用户权限就够了减少安全风险。启动方式大致如下# Windows windows-start.bat # macOS / Linux bash mac-start.command # 或 ./mac-start.command启动后Hermes 通常会在终端输出管理面板地址和默认提示。如果它提示你“打开 dashboard 并粘贴 token”说明 Gateway 的鉴权机制已经启动这一步不要跳过token 会在后面的 Gateway 配置里用到。4. Kanban 看板任务持久化与状态流转4.1 看板解决的问题Kanban 的核心价值可以用一句话概括把任务从“会话上下文”里解放出来变成系统里的持久化实体。在纯对话场景中Agent 的任务状态存在于模型上下文窗口里一旦进程退出或上下文超长前面的工作就白做了。在看板模式下任务状态存在于磁盘或数据库中Agent 随时可以重新加载。这就带来三个实际收益Agent 崩溃后重启进程可以继续消费未完成任务。多个 Agent 可以共享同一个看板按状态列领取任务实现协作。任务有完整的生命周期记录方便审计和回溯。4.2 看板配置示例Hermes 的看板配置一般使用 YAML 或 JSON。下面是一个最小可用的看板配置示例文件可以命名为kanban.yaml# kanban.yaml kanban: name: default storage: type: file path: ./data/kanban columns: - name: todo description: 新任务已创建等待 Agent 领取 - name: in_progress description: 任务已被 Agent 领取正在处理 - name: blocked description: 任务因依赖或错误被阻塞 - name: done description: 任务已完成可归档 retention: done_days: 7解释一下关键字段storage.type: file表示使用本地文件存储适合单机部署。生产环境如果支持更可靠的存储建议按官方文档切换到数据库或 Redis。columns定义了任务状态列。这里用了最常见的四列todo、in_progress、blocked、done。你可以根据业务增加列但核心原则是状态流转必须清晰。retention.done_days表示已完成任务保留 7 天后清理避免看板无限膨胀。4.3 创建任务并进行状态流转看板创建好之后可以通过命令行或管理界面提交任务。假设 Hermes 提供了hermes task命令操作逻辑大致如下# 创建看板如果尚未初始化 hermes kanban init --config kanban.yaml # 提交一个任务到 todo 列 hermes task create \ --title 处理用户工单 #1024 \ --description 用户反馈订单状态不一致需要比对三个数据源 \ --column todo \ --priority high任务提交后Agent 侧就能从看板拉取任务。一个典型的流转过程是入口 Agent 创建任务放入todo列。处理 Agent 从todo列领取任务将任务移动到in_progress列。如果处理过程中发现缺少依赖任务移动到blocked列。处理完成任务移动到done列。这种“看板驱动”的方式比直接给 Agent 发消息更可控。因为看板本身就是数据你可以随时检查任务状态、重试失败任务、甚至手动调整任务归属。4.4 持久化验证思路要验证持久化是否真正生效可以做一个很简单的实验提交一个任务把 Hermes 完全停掉再重新启动然后查询看板。如果任务还在todo或in_progress列说明持久化生效如果任务丢失优先检查storage.path配置和启动用户是否有写权限。这里要特别提醒不要把看板当成临时缓存它是多智能体协作的“唯一事实来源”。Agent 之间的交接、状态确认、故障恢复都应该以看板数据为准而不是以某个 Agent 的内存上下文为准。5. Gateway 网关连接、路由与模型分发5.1 Gateway 为什么必须是统一入口如果你有多个 Agent、对接多个模型服务商、同时还要被多个外部客户端调用最朴素的做法是每个客户端各自保存 API Key、各自直连模型。但这种方案在规模变大之后会非常痛苦Key 分散、无法统一审计、模型切换要改所有客户端。Gateway 就是为了解决这个问题。它作为一个统一入口对外暴露稳定的连接地址对内路由到不同模型提供商。外部客户端只知道 Gateway不需要关心背后到底用的是 DeepSeek 还是其他兼容服务。从社区反馈的信息看Hermes 的 Gateway 至少承担了三件事Token 鉴权客户端必须携带有效 token 才能访问解决“谁允许调用”的问题。模型路由根据请求中的模型名把请求转发到对应的模型服务商。协议转换将外部统一的请求格式转换为不同模型服务商期望的格式。5.2 Gateway 配置示例下面是一个最小网关配置示例文件可命名为gateway.yaml# gateway.yaml gateway: host: 127.0.0.1 port: 18789 ws_port: 18789 token: ${HERMES_GATEWAY_TOKEN} providers: - name: deepseek type: openai_compatible base_url: https://api.deepseek.com/v1 api_key: ${DEEPSEEK_API_KEY} routes: - model: deepseek-chat provider: deepseek upstream_model: deepseek-chat - model: hermes-default provider: deepseek upstream_model: deepseek-chat关键配置说明token建议通过环境变量注入不要明文写在配置里。启动 Gateway 时控制台提示的“打开 dashboard 并粘贴 token”就是在引导你获取这个值。providers定义实际对接的模型服务商。这里以 DeepSeek 为例type: openai_compatible表示它兼容 OpenAI 风格的接口。routes定义模型路由。外部客户端请求hermes-default时Gateway 会把它转发到deepseek提供商的deepseek-chat模型。5.3 启动 Gateway 与验证连通性启动 Gateway 后可以用 curl 做一次最基础的连通性验证curl http://127.0.0.1:18789/health \ -H Authorization: Bearer $HERMES_GATEWAY_TOKEN如果返回正常说明 Gateway 基本可用。如果返回unauthorized: gateway token missing说明请求头里没有带 token或者 token 不对。如果返回 502则说明 Gateway 本身可能没启动或者后端模型服务不可达。对于一个 OpenAI 兼容的响应接口请求方式可能类似curl -X POST http://127.0.0.1:15721/v1/responses \ -H Authorization: Bearer $HERMES_GATEWAY_TOKEN \ -H Content-Type: application/json \ -d { model: hermes-default, input: 你好请做一个自我介绍 }注意实际接口路径要以你安装版本的文档为准这里展示的是社区常见形态。5.4 理解常见 Gateway 报错从热搜词里可以看到常见报错集中在几类报错信息初步判断unexpected status 502 bad gatewayGateway 无法访问后端服务或本地代理冲突gateway: not reachable at ws://127.0.0.1:18789Gateway 未启动或 WebSocket 端口不对unauthorized: gateway token missing请求缺少 tokendoesn’t look like an anthropic model: expected a gateway model route模型路由配置缺失Gateway 不知道将该模型转发到哪个 provider这些报错里502 是最容易让人困惑的。很多情况下它并不是模型服务商挂了而是本地代理端口冲突或 Gateway 配置里base_url指向不可达。排查时先确认 Gateway 进程是否存活再检查 provider 的连通性。6. 完整示例让 Agent 7×24 待命这一节给出一个完整的最小闭环。目标是一个入口 Agent 接收任务并写入看板一个处理 Agent 从看板领取任务并调用模型完成处理Gateway 负责统一模型路由整个系统即使重启也能从看板恢复未完成任务。6.1 项目目录结构hermes-demo/ ├── data/ │ └── kanban/ ├── config/ │ ├── gateway.yaml │ ├── kanban.yaml │ └── agents.yaml ├── skills/ │ └── customer_service/ └── start.shdata/kanban用于存放看板文件config放配置文件skills放 Agent 技能。6.2 Gateway 配置沿用上一节的gateway.yaml把它放到config/gateway.yaml。启动前设置环境变量export HERMES_GATEWAY_TOKEN$(openssl rand -hex 16) export DEEPSEEK_API_KEYyour_deepseek_api_key这样 token 不会出现在配置文件中也避免了误提交到 Git 仓库。6.3 Kanban 配置将上一节的kanban.yaml放到config/kanban.yaml。如果使用文件存储确保data/kanban目录存在并且有写权限mkdir -p data/kanban6.4 Agent 配置示例下面是一个简单的 Agent 配置假设有一个入口 Agent 和一个处理 Agent# agents.yaml agents: - name: dispatcher role: 任务调度 description: 接收外部请求创建看板任务 kanban: default - name: worker role: 任务处理 description: 从看板领取 todo 任务调用模型处理 kanban: default watch: column: todo on_claimed: move_to_in_progress这个配置表达了一种常见的“调度者 执行者”模式dispatcher负责创建任务不直接处理worker监听todo列一旦有任务就领取并把它改为in_progress。这是多智能体系统里非常经典的串联模式。好处是责任清晰入口 Agent 可以快速响应外部请求处理 Agent 专注执行不会因为模型响应慢而阻塞入口。6.5 启动流程将启动命令写入start.sh#!/usr/bin/env bash set -e export HERMES_GATEWAY_TOKEN${HERMES_GATEWAY_TOKEN:-$(openssl rand -hex 16)} echo 1/3 启动 Gateway hermes gateway start --config config/gateway.yaml echo 2/3 初始化 Kanban hermes kanban init --config config/kanban.yaml echo 3/3 启动 Agent hermes agent start --config config/agents.yaml注意Gateway 启动后如果控制台提示需要粘贴 token说明当前 Shell 环境变量没有正确传入。更稳妥的方式是确认HERMES_GATEWAY_TOKEN已导出再启动 Gateway。6.6 提交任务验证闭环系统启动后向看板提交一个任务hermes task create \ --title 查询订单状态 \ --description 用户想知道订单 #A12345 当前是否已发货 \ --column todo \ --priority normal如果配置正确workerAgent 会从todo列领取任务将其标记为in_progress然后调用 Gateway 路由到的模型处理任务完成后把任务移到done列。到这一步你就拥有一个最简的 7×24 待命 Agent 系统了。所谓“待命”不是说模型一直在线而是看板上的任务一直存在Agent 进程随时可以接手。7. 运行结果与效果验证7.1 查看 Gateway 日志Gateway 启动后终端通常会输出类似下面的信息[INFO] Gateway listening on ws://127.0.0.1:18789 [INFO] Route registered: hermes-default - deepseek/deepseek-chat [INFO] Health check endpoint: /health这不是固定格式不同版本输出会不同但关键点是看到监听地址和路由注册成功说明 Gateway 基本正常。如果出现gateway: not reachable at ws://127.0.0.1:18789优先确认进程是否启动其次确认客户端连接地址是否写的是127.0.0.1而不是localhost。在某些网络环境下localhost可能解析到 IPv6 地址::1导致连接不上。7.2 查看看板状态提交任务后通过以下方式查看看板hermes kanban list --config config/kanban.yaml预期能看到类似这样的状态| ID | Title | Column | Priority | Updated At | | --- | -------------- | ------------ | -------- | ------------------- | | 1 | 查询订单状态 | in_progress | normal | 2025-06-01 10:22:00 |如果任务一直停留在todo列说明没有 Agent 领取或者 Agent 没有配置监听todo列。先检查 Agent 日志。7.3 验证持久化做一个关键实验提交一个任务后不处理完就停止 Hermes然后重新启动。# 停止所有 Hermes 进程 pkill -f hermes # 重新启动 bash start.sh # 再次查询看板 hermes kanban list --config config/kanban.yaml如果任务还在看板中且状态和重启前一致说明 Kanban 持久化生效。这一条是整个“7×24 待命”的核心验证点值得认真做一次。7.4 验证 Gateway 鉴权分别用“带 token”和“不带 token”的方式请求 Gateway验证鉴权是否生效# 不带 token应该被拒绝 curl http://127.0.0.1:18789/health # 带 token应该通过 curl http://127.0.0.1:18789/health \ -H Authorization: Bearer $HERMES_GATEWAY_TOKEN如果两种情况都返回 200说明鉴权没有生效或配置不对这时候要回到gateway.yaml检查token字段。8. 常见问题与排查方法以下是根据社区高频问题和实际工程经验整理的排查表问题现象可能原因排查方式解决方案启动时提示“gateway 未启动 · 请先运行 windows-start.bat 或 mac-start.command”Gateway 进程没有启动或启动脚本执行失败检查终端是否输出 Gateway 启动日志先运行对应系统的启动脚本确认 Gateway 监听端口出现unexpected status 502 bad gateway: unknown errorGateway 无法访问后端模型服务或本地端口被代理拦截检查 provider 的base_url和 API Key检查本地代理环境变量确保模型服务商接口可达临时取消本地代理或在 Gateway 配置中跳过代理gateway: not reachable at ws://127.0.0.1:18789Gateway 未启动或客户端连接地址错误确认端口是否监听检查是否用了 localhost 导致 IPv6 解析差异使用127.0.0.1连接先启动 Gateway 再启动 Agentunauthorized: gateway token missing请求头缺失 token或 token 配置不一致打印启动时使用的环境变量对比配置文件使用统一的环境变量注入 token不要复制错 tokenthe agent execution provider did not respond in timeAgent 执行器调用模型或工具超时查看是哪个 provider 超时检查网络和模型响应时间适当调大超时时间先手动调用模型接口确认耗时doesn’t look like an anthropic model: expected a gateway model route模型路由配置缺失Gateway 不知道如何转发检查请求中的 model 名是否在routes中注册在 routes 中添加对应模型路由或修改客户端请求的 model 名称任务一直停留在todo列Agent 没有监听该列或 Agent 未启动查看 Agent 日志确认 watch 配置确保agents.yaml中监听列名和看板列名一致排查时有一个推荐顺序先看进程再看端口再看配置最后看日志。不要一开始就怀疑模型服务商大多数本地报错都是配置和连接问题。9. 最佳实践与工程建议9.1 安全边界Token 和权限Gateway 的 token 是整个系统的入口钥匙务必用环境变量管理不要提交到 Git。生产环境建议单独建一个只有只读权限的 token用于外部客户端接入管理员操作使用另一个高权限 token。如果 token 泄露要能立即吊销并重新生成。9.2 看板任务设计看板任务尽量使用全局唯一 ID并在任务描述中附带足够的上下文。Agent 重启后恢复任务时不应该依赖内存中的对话记录而应该能从任务 ID 重新拉取必要信息。这个设计会影响崩溃恢复的可靠性。9.3 模型路由统一建议在 Gateway 中定义一套内部模型别名比如hermes-default所有 Agent 和客户端只使用别名不直接写模型供应商的真实模型名。这样以后切换模型服务商时只需要修改 Gateway 的 routes不需要逐个修改 Agent 配置。真实场景中的一个例子你上午用deepseek-chat下午想换成一个更快的模型如果所有客户端都写死了deepseek-chat就要改很多地方但如果统一走hermes-default只需在 Gateway 的 routes 里改一行。9.4 超时与重试多智能体系统里模型调用超时是常态不是异常。Gateway 和服务端都应该配置合理的超时和重试策略。对于执行 provider 超时的问题调整超时参数前先确认模型服务商的真实响应时间避免因为网络抖动而误判。9.5 可观测性Gateway 是可观测性的最佳切入口。建议记录每次请求的模型名、路由目标、状态码、耗时和 token 消耗。这些数据不仅是排查问题的依据也是做成本分析的基础。9.6 从最小闭环开始不要一上来就把 Agent 拆成十几个微服务。先用一个 dispatcher 和一个 worker通过看板串联起来跑通“创建任务—领取任务—完成迁移”的最短路径再加入更多 Agent 和复杂技能。如果初版配置就支撑不起最小闭环后续复杂化只会更难排查。9.7 不要忽略 Agent 安全Agent 能调用工具就意味着有执行能力。生产环境中要给 Agent 的技能配置权限边界例如文件操作限定在指定目录、网络请求限定在可信域名。看板中的 blocked 列也可以作为一种人工审批机制让高危险任务在进入执行前先被阻塞等待人工确认。10. 总结与后续学习方向这篇文章从“多智能体为什么需要工程组件”出发拆解了 Hermes 中两个容易被忽视但至关重要的模块Kanban 和 Gateway。看懂了它俩你就理解了很多 Agent 框架设计的底层逻辑——任务不能活在会话里连接不能散落在各处。配置并跑通一个“入口 Agent 创建任务、处理 Agent 领取任务、模型请求走 Gateway 路由”的最小闭环才是把 Agent 从“聊天玩具”推向“值班助手”的关键一步。下一步建议按这个顺序继续深入先熟练 Kanban 的状态设计和任务恢复再研究 Gateway 的模型路由和 token 安全策略然后进入 Skill 开发让 Agent 真正具备工具调用能力。后面还可以关注 Hermes 与 MCPModel Context Protocol多智能体的集成方式这是把外部工具和 Agent 能力打通的常见路径。最后提醒一句配置多智能体系统时务必从最小闭环做起先保证任务不丢、连接不断、日志可查再谈复杂协作。