🩺 常见问题与故障排除

兜底篇 — 装不上、连不上、报错了？来这里找答案

---

🔴 Claude Code 常见问题

Q1: npm install -g 报 EACCES 权限错误

# 错误信息：
# Error: EACCES: permission denied, mkdir '/usr/lib/node_modules/@anthropic-ai'

# 解决：用 sudo
sudo npm install -g @anthropic-ai/claude-code

# 或改用用户级 npm
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g @anthropic-ai/claude-code

Q2: claude 命令找不到

# 检查 npm 全局路径
npm list -g --depth=0 | grep claude

# 如果没装
npm install -g @anthropic-ai/claude-code

# 如果装了但找不到，检查 PATH
echo $PATH | grep npm
which claude

Q3: 认证失败 / 401 错误

# 检查环境变量
echo $ANTHROPIC_API_KEY
echo $ANTHROPIC_BASE_URL

# 检查认证状态
claude auth status --text

# 重置认证
unset ANTHROPIC_API_KEY
unset ANTHROPIC_BASE_URL
# 重新 export（见安装指南）

Q4: DeepSeek 报模型不存在

# 错误：Model not found

# 检查模型名是否正确
# deepseek-v4-pro 必须加 [1m] 后缀
# deepseek-v4-flash 不加后缀

# 正确：
export ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic"
claude -p "test" --model deepseek-v4-pro[1m] --max-turns 1

Q5: Claude Code 一直跑不停

# 设最大轮数限制
claude -p "任务" --max-turns 10

# 设预算上限
claude -p "任务" --max-budget-usd 0.5

# 交互模式按 Ctrl+C 停止当前任务

Q6: python 命令找不到

Claude Code 可能调用 python（而不是 python3）。

Linux (Ubuntu/Debian):

sudo apt install python-is-python3

macOS:

# macOS 通常已有 python3，创建别名即可
# 注意：直接 ln -s 可能被 SIP 拦截，推荐用 alias
echo 'alias python=python3' >> ~/.zshrc
source ~/.zshrc

---

🟡 Hermes Agent 常见问题

Q1: 安装脚本下载失败

# 如果 GitHub 连不上，尝试：
# 1. 用代理
export https_proxy=http://127.0.0.1:7890
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

# 2. 手动克隆
git clone https://github.com/NousResearch/hermes-agent.git ~/.hermes/hermes-agent
cd ~/.hermes/hermes-agent
python3 -m venv venv
source venv/bin/activate
pip install -e .

Q2: hermes 命令找不到

# 安装脚本应该自动加了 PATH
# 如果没加，手动加
echo 'export PATH="$HOME/.hermes/hermes-agent/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# 或者用完整路径
~/.hermes/hermes-agent/bin/hermes

Q3: 模型连接失败

# 1. 检查 API Key
hermes config env-path    # 找到 .env 位置
cat ~/.hermes/.env | grep KEY

# 2. 检查模型配置
hermes config | grep -A5 model

# 3. 测试网络
curl -I https://api.deepseek.com

# 4. 重选模型
hermes model

Q4: 网关服务启动失败

# 看具体错误
tail -50 ~/.hermes/logs/gateway.log
journalctl --user -u hermes-gateway -n 50

# 重置失败状态
systemctl --user reset-failed hermes-gateway

# 手动前台运行看报错
hermes gateway run

Q5: SSH 断开后网关就挂了

# 启用 lingering（让用户服务在登出后继续跑）
sudo loginctl enable-linger $USER

# 重启网关
hermes gateway restart

Q6: WSL2 网关随窗口关闭

# 编辑 /etc/wsl.conf
sudo nano /etc/wsl.conf

# 加入：
[boot]
systemd=true

# 重启 WSL2
wsl --shutdown
wsl

Q7: 技能不生效 / 找不到

# 查看已安装技能
hermes skills list

# 技能配置变更后需要新会话
# 在对话中：/reset
# 在命令行：重新运行 hermes

# 手动加载技能
hermes -s skill名字

# 或在对话中
/skill skill名字

Q8: Discord Bot 不说话

必须开启 Message Content Intent！

Discord Developer Portal → Bot → Privileged Gateway Intents → 勾选 Message Content Intent

Q9: Slack Bot 只有私聊能回复

需要订阅 message.channels 事件

Slack App 设置 → Event Subscriptions → Subscribe to bot events → 添加 message.channels

---

🟢 通用问题

Q1: 怎么知道自己现在用的是什么模型？

# Claude Code
claude auth status --text

# Hermes
hermes config | grep default
# 或在对话中输入 /model

Q2: API Key 会不会泄露给 AI？

不会。两个工具都把 API Key 存在本地环境变量中，不会发给 AI 模型。

Q3: 能不能离线使用？

都不能。必须联网调用 AI API。如果想完全本地运行，需要用 Ollama + 本地模型，那是另一个话题。

Q4: 手机能用吗？

Q5: 怎么更新？

# Claude Code
claude update

# Hermes
hermes update

Q6: 怎么彻底卸载？

# Claude Code
npm uninstall -g @anthropic-ai/claude-code
rm -rf ~/.claude

# Hermes
hermes uninstall
# 或手动删
rm -rf ~/.hermes

---

🆘 还是搞不定？

1. 先看日志：~/.hermes/logs/gateway.log

2. 运行医生：hermes doctor 或 claude doctor

3. 重启大法：hermes gateway restart，对话中 /reset

4. 翻翻之前的对话：AI 可能已经解决过类似问题，直接问它"上次那个问题怎么修的？"

---

🔥 全流程避坑速查表

从零到两个都跑起来，下面这些坑按阶段排列，挨个对照能省你半天时间。

阶段一：装 Claude Code

阶段二：配 Claude Code

阶段三：装 Hermes Agent

阶段四：配 Hermes 网关

阶段五：日常使用

---

🔗 各笔记专属 FAQ 速查

每篇笔记末尾都有专属 FAQ 和避坑指南：

---

标签：#AI #教程 #故障排除 #FAQ