现在很多人折腾 AI Agent，最大的误区不是不会装，而是以为「装上了」就等于「能用了」。结果就是，界面开了，命令也敲了，模型也选了，最后不是 command not found，就是卡在权限审批，要么登录 403，要么工具死活不执行，再不然就是看起来会思考，实际上一步都走不出去。然后很多人就开始下结论：「AI Agent 还是玩具。」

话说得挺硬，问题排得挺软。很多时候，不是工具不行，是环境、权限、上下文、登录和执行链路里有一环根本没打通。OpenAI、Anthropic 和 Hermes 的官方文档，其实都已经把这些坑写得很清楚了，只是多数人安装的时候只看了第一屏命令，后面那些真正能救命的部分直接略过。人类对「快速开始」的热爱，往往和对「认真排错」的厌恶成正比。

如果把当前这类工具的故障归类，最常见的根因其实就五类：

| 类别 | 典型问题 | 涉及工具 |

把这五类搞明白，很多看起来很玄的错误，其实都能一层层拆开。

很多 AI Agent 的第一类错误，发生在安装阶段，但会拖到运行阶段才爆出来。最典型的就是 Claude Code。Anthropic 的官方排障页把常见情况列得很直白：

这些全都不是「模型智商不够」，而是安装环境本身没对上。尤其是 PATH 问题，是最常见也最容易被忽略的那一个。Claude 官方明确写了，安装成功但运行 claude 仍提示找不到命令，通常就是安装目录没有进入 PATH。

macOS/Linux 默认安装路径：~/.local/bin/claude Windows 默认安装路径：%USERPROFILE%.localbinclaude.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 官方 Quickstart 写得很明确：

• 装完记得 source ~/.bashrc 或 source ~/.zshrc 让 shell 重新加载

很多人最大的问题不是 Hermes 难装，而是硬把 Linux 风格的安装命令怼进 Windows 原生终端里，然后惊讶地发现世界并不会因此变得更友善。

第二类问题，最常让人误以为「官方炸了」或者「模型把我封了」。其实很多时候，锅并没有那么宏大，就是认证链没打通。

| 错误提示 | 原因 | 解决方案 | |----------|------|----------| | 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 的认证更像「你是不是从一开始就选错了 provider」。官方 Quickstart 给了几条默认建议：

| 场景 | 推荐 Provider | |------|---------------| | 最少折腾 | Nous Portal / OpenRouter | | 已有 Claude/Codex 认证 | Anthropic / OpenAI Codex | | 本地/私有推理 | Ollama / OpenAI-compatible endpoint |

Hermes 的运行质量，很大程度上取决于你是不是从 provider 这一步就选了匹配自己场景的路。你要是拿低上下文、本地随便拉的小模型去跑多步工具链，再骂 Hermes 不会干活，这就像拿自行车去拉挖掘机，然后投诉机械工业退步。

如果你最近在折腾 Hermes Agent，这一条一定得单拎出来。因为它不是「可能相关」，而是官方直接写在 Quickstart 里的硬要求。

Hermes 要求模型上下文窗口至少 64K tokens

原因也写得很直白：小于这个窗口的模型，无法维持多步工具调用工作流所需的工作记忆，会在启动时被拒绝。

llama.cpp：

--ctx-size 65536 

Ollama：

-c 65536 

先确认模型上下文窗口，比你在群里问十遍「有人遇到过吗」有用得多。

这是当前 AI Agent 最容易被误解的一类问题，尤其在 Codex 和 Claude Cowork 这类开始接触电脑操作和长任务的工具上特别常见。

OpenAI 官方文档建议：

1. 打开终端跑基本命令试探：git status、pwd
2. 终端面板卡住？用 Cmd+J 重开

问题 1：侧边栏出现「Codex 没改过的文件」

问题 2：worktree 里的代码跑不起来

很多「AI 把环境搞坏了」的表面症状，实际上只是你把 Git 视图、worktree 和本地项目目录混成了一团。

OpenAI 的 ChatGPT agent 帮助文档反复强调：

Anthropic 对 Cowork 也强调，它有 agentic 特有风险和网络访问风险。

有时候你觉得它卡，其实是它在等你，或者在权限边界上被设计得必须慢下来。

如果你在 macOS 上用 Codex、Claude Cowork 这类会碰本地目录和桌面环境的工具，一定要把「系统权限弹窗」单独当成一级故障源。

Codex 官方文档提到：

很多人看到系统突然跳出一个访问 Apple Music 或 Desktop 的权限请求，第一反应不是「系统权限在拦」，而是「这玩意是不是疯了」。其实 OpenAI 文档已经写明了，这通常只是文件系统导航触发的额外审批。

Claude Cowork 甚至在入门文档里先让你跑 readiness check，而不是直接让你开干。官方提供了 macOS、Windows arm64、Windows x64 的检测程序。

只要检测结果显示 「This computer is ready for Cowork」，再往下走。

这说明 Anthropic 自己也清楚，这类 Agent 的第一道门槛，常常不是模型，而是宿主机环境是否达标。

| 工具 | 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 版本不一致？终端卡死？某个实验性功能不稳定？

这个顺序的意义就在于，它能帮你避开一种最浪费时间的死法：

AI Agent 现在确实越来越强了，但「越来越强」和「越来越不容易出错」不是一回事。越往执行层走，工具越像同事，也越像系统工程。

Claude Code、Codex、Hermes Agent 这些东西，真正难的从来不是第一条安装命令，而是后面那整条安装、认证、模型、权限、执行、恢复的链路有没有全通。

所以别再用一句「装上了为什么还不能用」来概括一切了。对这类工具来说，能启动只是开始，能稳定执行才算真装好。