现在很多人折腾 AI Agent，最大的误区不是不会装，而是以为「装上了」就等于「能用了」。结果就是，界面开了，命令也敲了，模型也选了，最后不是 command not found，就是卡在权限审批，要么登录 403，要么工具死活不执行，再不然就是看起来会思考，实际上一步都走不出去。然后很多人就开始下结论：「AI Agent 还是玩具。」
话说得挺硬，问题排得挺软。很多时候，不是工具不行，是环境、权限、上下文、登录和执行链路里有一环根本没打通。OpenAI、Anthropic 和 Hermes 的官方文档，其实都已经把这些坑写得很清楚了，只是多数人安装的时候只看了第一屏命令，后面那些真正能救命的部分直接略过。人类对「快速开始」的热爱，往往和对「认真排错」的厌恶成正比。
如果把当前这类工具的故障归类，最常见的根因其实就五类：
| 类别 | 典型问题 | 涉及工具 | |------|----------|----------| | 安装环境 | Shell 用错、PATH 没加、Windows 装法不对 | Claude Code、Hermes | | 认证授权 | OAuth 失效、403、token 过期、provider 选错 | Claude Code、Hermes | | 执行条件 | 上下文窗口太小、readiness check 未通过 | Hermes、Claude Cowork | | 权限审批 | Agent 卡住等确认、系统权限弹窗 | Codex、Claude Cowork | | 产品问题 | worktree 未就绪、终端卡死、版本不同步 | Codex、Claude Code |
把这五类搞明白，很多看起来很玄的错误，其实都能一层层拆开。
一、第一步先别急着怪模型，先看安装链是不是从一开始就歪了
很多 AI Agent 的第一类错误，发生在安装阶段，但会拖到运行阶段才爆出来。最典型的就是 Claude Code。Anthropic 的官方排障页把常见情况列得很直白：
- command not found
- Windows 下 PowerShell 命令不匹配
- Windows 需要 Git Bash
- 32 位 Windows 不支持
- Linux 下 Illegal instruction
- macOS 出现 dyld 错误
- TLS 证书错误
- 公司网络下 CA 证书问题
这些全都不是「模型智商不够」，而是安装环境本身没对上。尤其是 PATH 问题，是最常见也最容易被忽略的那一个。Claude 官方明确写了，安装成功但运行 claude 仍提示找不到命令，通常就是安装目录没有进入 PATH。
macOS/Linux 默认安装路径：~/.local/bin/claude
Windows 默认安装路径：%USERPROFILE%\.local\bin\claude.exe
如果 PATH 里没有这条，就会出现「明明装了却跑不起来」的经典闹剧。
修复方法
Zsh 用户：
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
claude --version
Bash 用户：
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
claude --version
Windows 用户注意：Claude Code on Windows requires Git Bash，而且 32 位 Windows 不支持。命令、Shell 和架构三样只要错一样，就够你折腾半天。
Hermes Agent 安装注意事项
Hermes 官方 Quickstart 写得很明确：
- 安装命令适用于 Linux、macOS、WSL2、Android Termux
- Windows 用户要先装 WSL2，再在 WSL2 终端里跑安装脚本
- 装完记得
source ~/.bashrc或source ~/.zshrc让 shell 重新加载
很多人最大的问题不是 Hermes 难装，而是硬把 Linux 风格的安装命令怼进 Windows 原生终端里，然后惊讶地发现世界并不会因此变得更友善。
二、登录、403、OAuth、token 过期，这些问题看着像账号问题，本质是认证链断了
第二类问题，最常让人误以为「官方炸了」或者「模型把我封了」。其实很多时候，锅并没有那么宏大，就是认证链没打通。
Claude Code 常见认证问题
| 错误提示 | 原因 | 解决方案 | |----------|------|----------| | OAuth error: Invalid code | 登录 code 过期或复制截断 | 重新获取 code | | 403 Forbidden after login | 认证失败或区域限制 | 检查网络/区域可用性 | | Not logged in or token expired | Token 失效 | 重新登录 | | Model not found or not accessible | 模型授权或区域问题 | 检查模型可用性 | | App unavailable in region | 地理区域限制 | 无法通过重试解决 |
最常见原因：在远程/SSH 会话里执行登录，浏览器却在另一台机器上打开。
解决方案：复制终端里给出的 URL，到本地浏览器里打开。
Hermes Agent 认证链
Hermes 的认证更像「你是不是从一开始就选错了 provider」。官方 Quickstart 给了几条默认建议：
| 场景 | 推荐 Provider | |------|---------------| | 最少折腾 | Nous Portal / OpenRouter | | 已有 Claude/Codex 认证 | Anthropic / OpenAI Codex | | 本地/私有推理 | Ollama / OpenAI-compatible endpoint |
Hermes 的运行质量，很大程度上取决于你是不是从 provider 这一步就选了匹配自己场景的路。你要是拿低上下文、本地随便拉的小模型去跑多步工具链，再骂 Hermes 不会干活，这就像拿自行车去拉挖掘机，然后投诉机械工业退步。
三、Hermes 能启动但不工作，往往不是「笨」，而是上下文窗口根本不够
如果你最近在折腾 Hermes Agent，这一条一定得单拎出来。因为它不是「可能相关」，而是官方直接写在 Quickstart 里的硬要求。
Hermes 要求模型上下文窗口至少 64K tokens
原因也写得很直白：小于这个窗口的模型，无法维持多步工具调用工作流所需的工作记忆，会在启动时被拒绝。
本地模型配置建议
llama.cpp：
--ctx-size 65536
Ollama：
-c 65536
这条要求的两个现实含义
- 如果 Hermes 启动时报模型不满足要求，别把排障方向放到「是不是脚本没装全」上，先看你选的模型是不是天生不够格
- 如果你是本地推理，别只看「能不能出字」，要看它有没有足够上下文支撑工具链
典型症状
- 「能启动，但一到复杂任务就像失忆」
- 「工具链开始了，但半路就断」
- 「不是报错，而是工作质量莫名其妙垮掉」
先确认模型上下文窗口，比你在群里问十遍「有人遇到过吗」有用得多。
四、Agent 看起来「卡死」了，很多时候不是死了，是在等你点批准
这是当前 AI Agent 最容易被误解的一类问题，尤其在 Codex 和 Claude Cowork 这类开始接触电脑操作和长任务的工具上特别常见。
Codex 排障顺序
OpenAI 官方文档建议：
- 检查 Codex 是否在等待 approval
- 打开终端跑基本命令试探：
git status、pwd - 开一个更小、更聚焦的新线程
- 终端面板卡住？用
Cmd+J重开 - 等活跃线程完成后重启 app
常见误判：Git 状态和 worktree
问题 1：侧边栏出现「Codex 没改过的文件」
- 原因：review panel 默认展示整个 Git state，不只是本轮改动
- 解决：切到 「Last turn changes」只看本轮改动
问题 2：worktree 里的代码跑不起来
- 原因：worktree 目录只继承已提交进 Git 的文件，依赖需要额外 setup
- 解决：在 local environment 里跑 setup
很多「AI 把环境搞坏了」的表面症状，实际上只是你把 Git 视图、worktree 和本地项目目录混成了一团。
权限保护让 Agent 看起来「更慢、更笨」
OpenAI 的 ChatGPT agent 帮助文档反复强调：
- 敏感输入要用 takeover mode，不要把密码直接打进消息里
- 只启用当前任务需要的 app
- 看到可疑行为立刻停止任务
Anthropic 对 Cowork 也强调，它有 agentic 特有风险和网络访问风险。
有时候你觉得它卡，其实是它在等你，或者在权限边界上被设计得必须慢下来。
五、macOS 和 Windows 的「系统权限」坑，比模型本身更容易劝退人
macOS 权限问题
如果你在 macOS 上用 Codex、Claude Cowork 这类会碰本地目录和桌面环境的工具，一定要把「系统权限弹窗」单独当成一级故障源。
Codex 官方文档提到：
- Music、Downloads、Desktop 等目录需要用户额外授权
- 如果 Codex 要读 home directory，macOS 可能会弹系统级确认
很多人看到系统突然跳出一个访问 Apple Music 或 Desktop 的权限请求，第一反应不是「系统权限在拦」，而是「这玩意是不是疯了」。其实 OpenAI 文档已经写明了，这通常只是文件系统导航触发的额外审批。
Claude Cowork readiness check
Claude Cowork 甚至在入门文档里先让你跑 readiness check，而不是直接让你开干。官方提供了 macOS、Windows arm64、Windows x64 的检测程序。
只要检测结果显示 「This computer is ready for Cowork」，再往下走。
这说明 Anthropic 自己也清楚，这类 Agent 的第一道门槛，常常不是模型，而是宿主机环境是否达标。
Windows 兼容性地狱
| 工具 | Windows 要求 | |------|-------------| | Claude Code | Git Bash 必需，32 位不支持，PowerShell 命令可能不匹配 | | Hermes | 推荐 WSL2，原生 Windows 不是推荐路径 |
意思已经很明白了：别用「我平时怎么装普通软件」那套经验来套 AI Agent。
这类工具很多默认前提是 Linux/macOS 风格的终端、路径、shell 和权限模型。你硬拿 Windows 原生环境去顶，有时不是不能成，而是你要比别人多交一倍排障学费。
六、真正实用的排障顺序
说了这么多，最后给一个最实用的结论。AI Agent 这类工具的排障，最怕的不是问题复杂，而是你一开始就乱了顺序。
按层排查法
第一层：安装层
↓ 命令对不对？Shell 对不对？PATH 在不在？Windows 是不是该用 WSL2/Git Bash？
第二层：认证层
↓ OAuth code 过期？token 失效？登录 URL 开错机器？provider 选错？
第三层：执行环境层
↓ Hermes 上下文够 64K？Cowork readiness check 过了？worktree 准备好依赖？
第四层：权限与审批层
↓ 是真的卡住还是在等批准？系统目录权限没放？安全设计让它必须慢下来？
第五层：产品自身问题
↓ CLI 和 app 版本不一致？终端卡死？某个实验性功能不稳定？
这个顺序的意义就在于，它能帮你避开一种最浪费时间的死法：
- 把环境问题当模型问题
- 把权限问题当智商问题
- 把配置问题当产品 bug
结语
AI Agent 现在确实越来越强了，但「越来越强」和「越来越不容易出错」不是一回事。越往执行层走，工具越像同事，也越像系统工程。
Claude Code、Codex、Hermes Agent 这些东西，真正难的从来不是第一条安装命令，而是后面那整条安装、认证、模型、权限、执行、恢复的链路有没有全通。
所以别再用一句「装上了为什么还不能用」来概括一切了。对这类工具来说，能启动只是开始，能稳定执行才算真装好。
问题求助
没能解决你的问题？直接问我
如果你遇到任何技术问题无法解决，可以在这里提交求助。我会尽快查看并回复你。
支持作者
如果这篇文章帮到了你，可以支持我
扫码打赏，支持我持续更新原创排障文章。
