本地 Agent 刚跑起来的时候很容易让人兴奋：它能读项目、接工具、跑命令、连模型，甚至通过 Gateway 接到聊天软件和定时任务。但真正用一段时间以后，很多人会发现最耗时间的不是第一次安装，而是坏了以后不知道从哪里查。它能聊天，但工具不生效；模型配置看起来对，但 Gateway 用的还是旧配置；MCP 显示已经加上了，但实际调用不到；更新以后 skills、memory、config 又像断了一层。
这类问题不只出现在 Hermes。OpenClaw、OpenHands、Claude Code、Codex、Cline、Dify 本地部署和各种 MCP 组合都会遇到类似情况。原因也很直接：本地 Agent 不是一个单独 App，它是模型、配置、运行时、工具、权限和本地环境叠在一起。排障时如果同时改模型、改配置、重装依赖、重启 Gateway，很容易把问题越修越乱。
更好的方式，是先按层定位。
第一层：命令和运行时能不能正常启动
如果连主命令都跑不起来，先不要急着查模型、MCP 或工具调用。先看安装和运行时：命令是否在 PATH 里，Python、Node、Docker 或 uv 版本是否满足要求，当前是在 Windows、WSL2、macOS、Linux 还是容器里跑，权限是不是把程序装到了另一个用户目录。
Hermes 中文故障页也把这个顺序放在最前面：如果 hermes 命令都执行不了，就先看安装和环境问题，不要直接去查 provider、Gateway 或 MCP。OpenClaw 的 FAQ 也把 openclaw health --verbose、配置路径、Gateway 可达性放在排查入口里。OpenHands 本地部署文档则明确把本地运行、模型设置和 runtime 镜像分开处理。
这一层可以只做几件事：确认版本号能打印出来，确认 doctor / health / status 这类诊断命令能跑，确认当前终端和服务进程用的是同一个用户、同一份配置和同一套环境变量。命令层不稳定时，后面所有模型和工具问题都不可靠。
第二层：模型、API Key、base_url 和 model id 是否对齐
命令能启动以后，下一层看模型。很多本地 Agent 问题最后都落在这里：API Key 过期、provider 选错、OpenAI key 拿去填 OpenRouter、base_url 少了 /v1、model id 写成页面展示名而不是接口需要的名字，或者余额、限速、上下文长度不对。
Hermes 的模型配置文档强调通过 hermes model 选择 provider 和 model，并把结果写进 ~/.hermes/config.yaml。它也提醒，已经打开的 chat session 是一个活的 agent 进程，可能继续使用启动时的模型配置；如果希望 Gateway 和会话拿到新设置，需要检查 hermes status，必要时重启 Gateway 或新开会话。这个细节很容易被忽略：你明明改了配置，但当前会话没有换。
如果你接的是本地模型，还要多看两件事。第一，模型是否真的支持稳定工具调用。社区里有人反馈，本地模型在直接 curl 测试时能返回工具调用，但进入完整 Agent 框架后，面对一整套工具描述会循环、误用工具或根本不调用。第二，上下文长度和工具描述会占用大量 prompt 空间。工具越多，模型越容易被无关工具干扰。
这一层的排查顺序可以很固定：先跑 status / model 命令确认当前生效配置，再用一个最小问答确认模型能返回，再用一个最小工具任务确认它能按格式调用工具。不要一上来就把 10 个 MCP server 和 20 个 tools 全开。
第三层：Tools、Skills、MCP 有没有真的被加载
能聊天不代表 Agent 能做事。很多人卡在这里：模型回答很正常，但 tools 列表为空；skills 没加载；MCP server 配置看起来存在，但 agent 调不到；浏览器、shell、文件工具被拒绝；Zapier、GitHub、Graph 这类外部工具连不上。
Hermes 的问题页专门把 Tools / Skills / MCP 单独列成一类，OpenClaw 也有 skills 配置和 Gateway 配置说明。这里最容易出错的地方是“配置存在”和“运行时真的加载”不是一回事。配置文件里写了 server，不代表当前 profile 用它；skills 文件夹里有内容，不代表格式和路径符合当前版本；MCP server 能启动，不代表 Agent 有权限调用它暴露的工具。
这层排障要从最小工具集开始。先只开一个低风险工具，比如读取当前目录、列出一个测试文件、调用一个只读 API。确认这一项能工作以后，再逐步加 shell、browser、web search、image generation 或外部 SaaS 工具。工具越多，越要分组加载。社区里关于 Hermes tool bloat 的讨论也提到，过多工具描述会挤占上下文，还会让模型在语义相近的工具之间选错。
MCP 还要单独看安全和信任。OWASP 对 MCP Tool Poisoning 的描述很直接：外部 MCP server 返回的内容可能携带隐藏指令，诱导 Agent 调用更高权限工具、读取敏感文件或外传数据。HashiCorp 的 Vault MCP 安全文档也建议本地运行、限制 token 权限、关闭不需要的高权限操作。把 MCP 当作“插件市场”随便加，是本地 Agent 最容易失控的地方之一。
第四层：Gateway、Docker、远程后端和消息入口是否在同一套环境里
Hermes 和 OpenClaw 这类工具经常有 Gateway、CLI、TUI、Web UI、消息机器人、cron job、Docker 后端或远程 backend。用户容易误以为“CLI 能聊”等于“Gateway 也能用”。实际上 Gateway 可能拿的是旧 PATH、旧 env、旧 config，Docker 容器里也可能看不到你本机的文件、Node、Playwright、浏览器或模型服务。
Hermes Tool Gateway 文档里提到，工具调用可以通过 Nous Gateway 或用户自己的 direct API keys 路由。也就是说，web search、image generation、TTS、browser 这些工具，可能不是走同一套 key 和同一套配置。工具突然不能用时，先看它走 Gateway 还是直连 provider，再看订阅、token、环境变量和 Gateway 状态。
OpenClaw FAQ 里也把 Gateway 可达性、agents/sessions、provider config 和 runtime issues 分开。对于消息入口尤其要小心：Telegram、Discord、Slack、飞书、企业微信这类链路不通，不一定是模型问题，可能只是 Gateway 没启动、Webhook 没通、token 过期、只跑了 CLI 没跑服务进程。
这一层可以记住一个原则：从同一个入口验证。你打算用 CLI，就查 CLI 当前环境；你打算用 Gateway，就查 Gateway 进程拿到的配置；你打算用 Docker，就进容器里查文件、PATH、端口和环境变量。不要用本机终端的成功，去证明容器或服务进程也成功。
第五层：权限、API Key 和安全边界有没有收住
本地 Agent 最吸引人的地方，也是最危险的地方：它能读文件、跑 shell、接浏览器、调 API、改项目。权限一多，排障不能只问“为什么不能用”，还要问“它该不该能用”。
API Key 不建议直接塞进聊天上下文，也不要把 root token、长期有效 token、全权限 key 放给 Agent 随便读。HashiCorp 在 Vault MCP 文档里建议不要用 root 或 shared token，而是用权限受限的 end-user token。OWASP 对 MCP Tool Poisoning 的防护建议也包括：高权限工具隔离、服务端执行层做访问控制、敏感操作需要用户确认、维护 MCP server allowlist。
日常使用里可以把权限分三层：只读工具默认开，写文件和执行命令需要确认，涉及密钥、网络外传、删除、部署和付款的动作必须人工确认。这样会慢一点，但比把所有工具全开再事后追日志靠谱得多。
一套最小排障顺序
如果本地 Agent 今天突然不工作，可以按这个顺序走：
- 先跑 version / doctor / health / status，确认命令和服务能启动。
- 确认当前 provider、model、base_url、API Key 和余额，不要只看配置文件，要看运行时实际使用的值。
- 新开一个干净会话，用最小问题测试模型。
- 只开一个低风险工具，测试 tool calling。
- 再测试 MCP server、browser、shell、web search 或外部 SaaS 工具。
- 如果走 Gateway 或 Docker，就在对应进程/容器里查 PATH、env、端口和日志。
- 涉及文件、shell、密钥和外部请求时，先收权限，再逐步放开。
这套顺序看起来慢，但它能防止你同时改 5 个变量。对本地 Agent 来说，最怕的不是坏，而是你修到最后已经不知道到底是哪一步把它修好了。
继续往下看
参考来源
- Hermes Agent 中文站：遇到问题
- https://hermes-zh.com/docs/issues
- Hermes Agent Docs：Configuring Models
- https://hermes-agent.ru/docs/user-guide_configuring-models.html
- Hermes Agent Docs：Nous Tool Gateway
- https://hermes-agent.ru/docs/user-guide_features_tool-gateway.html
- OpenClaw FAQ
- https://docs.openclaw.ai/help/faq
- OpenHands Docs：Local Setup
- https://docs.openhands.dev/openhands/usage/run-openhands/local-setup
- OWASP：MCP Tool Poisoning
- https://owasp.org/www-community/attacks/MCP_Tool_Poisoning
- HashiCorp Developer：Vault MCP Server Security Model
- https://developer.hashicorp.com/vault/docs/mcp-server/security-model