99-02 · 常见问题 FAQ

装机 / 网络 / 账号 / Agent 使用层面的 30 条高频问题。遇到问题先在这里搜一下。

一、网络 / 代理

Q1：Clash Verge 装好了，但 `curl https://www.google.com` 还是不通？

按下面顺序排查：

是否打开了 Clash Verge？右上角图标在不在？
系统代理 / TUN 是否启用？建议 TUN 模式开。
当前节点是否可用？切到不同地区试试。
终端可能缓存旧代理 → 关掉重开终端。
公司网络 / 学校网络是否屏蔽了 TUN？换手机热点试试。

Q2：开了代理，但 `npm install` 还是慢/失败？

用 TUN 模式：所有终端流量自动走代理，无需配 npm proxy。

如果不用 TUN：手动配

bash

npm config set proxy http://127.0.0.1:7890
npm config set https-proxy http://127.0.0.1:7890

实在不行用国内镜像：npm config set registry https://registry.npmmirror.com

Q3：节点突然全部超时？

大部分情况是机场服务器被特定协议封了。
解决：在订阅卡片上点"刷新订阅" → 拉最新节点列表。
还不行：换协议（vless / hysteria2 / vmess）。
还不行：换备用机场（公司推荐两家备份）。

Q4：Clash Verge 启动后报"无法启动 service"？

macOS：xattr -dr com.apple.quarantine /Applications/Clash\ Verge.app
Windows：以管理员身份运行一次安装
Linux：检查 systemd 是否阻止 TUN 模块

二、Windsurf / IDE

Q5：Windsurf 登录公司账号后没有模型可选？

检查星火插件是否安装并正常运行
检查桌面端 xinghuo 工具是否启动并已登录
重启 Windsurf

Q6：Cascade（Agent 对话）一直在转圈不返回？

大概率是网络问题：切个节点
或是当前模型超长上下文被限速：切到 Sonnet
或是公司账号配额耗尽：找团队 Lead 换号

Q7：Tab 补全经常给出过时代码？

检查项目里是否有 CLAUDE.md 写明"用什么版本框架"
在文件顶部加一行注释：// using React 19, Tailwind v4，提示模型

Q8：Windsurf 修改了不该改的文件怎么回退？

Windsurf 自带 checkpoint：左下角时间轴，找到对应 checkpoint 一键回退
或者用 git：每个会话开始前先 git status 干净，事后 git restore 即可

三、Claude Code / Codex

Q9：`claude` 命令找不到？

确认 Node 已装：node -v
重新装：npm install -g @anthropic-ai/claude-code
看 npm 全局路径：npm config get prefix，确保它在你的 PATH

Q10：Claude Code 报"Authentication required"？

跑 claude login 重新授权
如果是 Pro 订阅过期，去官网续订
或切到 API Key 模式

Q11：跑长任务跑到一半 Token 用完？

/cost 看本次会话成本
/compact 压缩当前上下文
关键节点结果先存到文件，再 /clear 重开会话继续

Q12：怎么让 Claude Code 干完一件事就停下，不要继续乱搞？

在 prompt 里加一行硬约束：

完成上述任务后，停下并等待我的下一步指令。不要主动继续。

Q13：Codex 比 Claude Code 慢很多？

正常。Codex 默认走深推理（reasoning_effort=medium），简单任务可改成 low：

bash

codex -m gpt-5-codex -c model_reasoning_effort="low"

四、MCP

Q14：装的 MCP server 在 `/mcp` 里看不到？

确认安装命令成功（-s user 是写到用户级配置）
重启 Claude Code（一次完整退出再启动）
用 claude mcp list 看注册情况

Q15：MCP server 启动失败 / 一直报错？

看 stderr：claude mcp logs <name>
检查依赖（npx / python 是否在 PATH）
检查环境变量（如 GH_TOKEN 是否传入）

Q16：怎么禁用某个 MCP（暂时不想让模型用）？

bash

claude mcp disable <name>
# 用完再开
claude mcp enable <name>

五、Skills

Q17：Skill 写好了但 Agent 没自动加载？

最常见原因：description 写得太抽象。

yaml

# 差的
description: 用于代码相关的事

# 好的
description: 当用户要求"提交代码"、"git commit"、"写 commit message"时启用，按公司规范生成 conventional commit

Q18：Skill 自动加载错了 / 不该加载的时候加载了？

在 SKILL.md 里加"何时不要使用"段落
用 skill-creator 的 Eval 模式跑一遍

Q19：Skill 数量太多，会不会拖慢 Agent？

不会显著拖慢 —— Skill 是按需加载的，不会全部塞进上下文。但 SKILL.md 的描述会被预读，所以建议 个人 Skill < 30 个，定期清理。

六、Hermes / OpenClaw

Q20：Hermes 启动时一直卡在"detecting tools"？

大概率是 tmux 没装：apt install tmux / brew install tmux
Windows 用户必须用 WSL2

Q21：Hermes 在跑 Claude Code 时 TUI 显示乱码？

设环境变量：

bash

export TERM=xterm-256color
export LANG=en_US.UTF-8

Q22：OpenClaw 端口 7860 占用？

bash

# 看谁占用
lsof -i:7860
# 改 docker-compose.yml 里的端口映射

七、Obsidian / 知识库

Q23：Obsidian 同步怎么做？

公司推荐三选一：

Git 插件 + 公司私有仓库（最推荐）
iCloud / Dropbox 同步 Vault 文件夹
Obsidian Sync 官方付费服务

Q24：Vault 里有几千个文件，Claude 读不动？

用 obsidian-rag MCP，靠向量检索而不是全文读
或者按子目录读：> 帮我只读 ~/qdy-vault/40-Skills 下的内容

Q25：Vault 路径里有中文 / 空格，命令行处理报错？

重新组织 Vault 路径：用纯英文 + 短横线（~/qdy-vault）
或者命令里加双引号："~/我的 Vault"

八、账号 / 安全

Q26：API Key 怎么保管最安全？

❌ 不要写进代码 / 不要 commit
✅ 用环境变量：.env + .env 加进 .gitignore
✅ 公司机密 Key 用 1Password / Bitwarden / Vault
✅ 每 90 天 rotate 一次

Q27：误把 .env 提交到 git 了怎么办？

立即 rotate 所有 Key（最重要）
用 git filter-repo 或 BFG 清掉历史中的 .env
force push 重写远端历史
通知所有协作者重新 clone

Q28：公司账号被风控 / 限频？

找团队 Lead 申请二号
或者切到 CC Switch 的备用配置
不要用 VPN 频繁切换地区登录（容易触发风控）

九、其他

Q29：我电脑配置低，跑不动本地 LLM？

不用本地 LLM，用云端就好
实在要本地：Ollama + 7B 量化模型，CPU 也能跑
不要硬上 70B+ 模型，效果不如 4B 量化的 Llama 3 / Qwen

Q30：我有问题没在这里找到答案？

按下面顺序：

在 Obsidian Vault 里搜（也许同事记过）
在公司 IM 的 #ai-tools 频道搜历史消息
提问到 #ai-tools 频道，附 复现步骤 + 报错截图
解决后 → 把答案写回 Vault 或者本 FAQ

心法

每解决一个问题，就写一条到这份 FAQ 里。你今天踩过的坑，不要让下一位股东再踩一遍。

99-02 · 常见问题 FAQ ​

一、网络 / 代理 ​

Q1：Clash Verge 装好了，但 curl https://www.google.com 还是不通？ ​

Q2：开了代理，但 npm install 还是慢/失败？ ​

Q3：节点突然全部超时？ ​

Q4：Clash Verge 启动后报"无法启动 service"？ ​

二、Windsurf / IDE ​

Q5：Windsurf 登录公司账号后没有模型可选？ ​

Q6：Cascade（Agent 对话）一直在转圈不返回？ ​

Q7：Tab 补全经常给出过时代码？ ​

Q8：Windsurf 修改了不该改的文件怎么回退？ ​

三、Claude Code / Codex ​

Q9：claude 命令找不到？ ​

Q10：Claude Code 报"Authentication required"？ ​

Q11：跑长任务跑到一半 Token 用完？ ​

Q12：怎么让 Claude Code 干完一件事就停下，不要继续乱搞？ ​

Q13：Codex 比 Claude Code 慢很多？ ​

四、MCP ​

Q14：装的 MCP server 在 /mcp 里看不到？ ​

Q15：MCP server 启动失败 / 一直报错？ ​

Q16：怎么禁用某个 MCP（暂时不想让模型用）？ ​

五、Skills ​

Q17：Skill 写好了但 Agent 没自动加载？ ​

Q18：Skill 自动加载错了 / 不该加载的时候加载了？ ​

Q19：Skill 数量太多，会不会拖慢 Agent？ ​

六、Hermes / OpenClaw ​

Q20：Hermes 启动时一直卡在"detecting tools"？ ​

Q21：Hermes 在跑 Claude Code 时 TUI 显示乱码？ ​

Q22：OpenClaw 端口 7860 占用？ ​

七、Obsidian / 知识库 ​

Q23：Obsidian 同步怎么做？ ​

Q24：Vault 里有几千个文件，Claude 读不动？ ​

Q25：Vault 路径里有中文 / 空格，命令行处理报错？ ​

八、账号 / 安全 ​

Q26：API Key 怎么保管最安全？ ​

Q27：误把 .env 提交到 git 了怎么办？ ​

Q28：公司账号被风控 / 限频？ ​

九、其他 ​

Q29：我电脑配置低，跑不动本地 LLM？ ​

Q30：我有问题没在这里找到答案？ ​

心法 ​

99-02 · 常见问题 FAQ

一、网络 / 代理

Q1：Clash Verge 装好了，但 `curl https://www.google.com` 还是不通？

Q2：开了代理，但 `npm install` 还是慢/失败？

Q3：节点突然全部超时？

Q4：Clash Verge 启动后报"无法启动 service"？

二、Windsurf / IDE

Q5：Windsurf 登录公司账号后没有模型可选？

Q6：Cascade（Agent 对话）一直在转圈不返回？

Q7：Tab 补全经常给出过时代码？

Q8：Windsurf 修改了不该改的文件怎么回退？

三、Claude Code / Codex

Q9：`claude` 命令找不到？

Q10：Claude Code 报"Authentication required"？

Q11：跑长任务跑到一半 Token 用完？

Q12：怎么让 Claude Code 干完一件事就停下，不要继续乱搞？

Q13：Codex 比 Claude Code 慢很多？

四、MCP

Q14：装的 MCP server 在 `/mcp` 里看不到？

Q15：MCP server 启动失败 / 一直报错？

Q16：怎么禁用某个 MCP（暂时不想让模型用）？

五、Skills

Q17：Skill 写好了但 Agent 没自动加载？

Q18：Skill 自动加载错了 / 不该加载的时候加载了？

Q19：Skill 数量太多，会不会拖慢 Agent？

六、Hermes / OpenClaw

Q20：Hermes 启动时一直卡在"detecting tools"？

Q21：Hermes 在跑 Claude Code 时 TUI 显示乱码？

Q22：OpenClaw 端口 7860 占用？

七、Obsidian / 知识库

Q23：Obsidian 同步怎么做？

Q24：Vault 里有几千个文件，Claude 读不动？

Q25：Vault 路径里有中文 / 空格，命令行处理报错？

八、账号 / 安全

Q26：API Key 怎么保管最安全？

Q27：误把 .env 提交到 git 了怎么办？

Q28：公司账号被风控 / 限频？

九、其他

Q29：我电脑配置低，跑不动本地 LLM？

Q30：我有问题没在这里找到答案？

心法