Qoder 命令或工具执行失败——命令、权限、环境排查
问题现象
Agent 在执行过程中：
- 终端命令报错退出（exit code 非 0）；
- 工具调用显示失败；
- Agent 说权限不够，但你明明有；
- npm install / pip install 之类的依赖安装失败。
第一步：看退出码和错误输出
不要只看 Agent 说的「命令失败」——看 终端面板里的真实输出：
- Agent 跑了什么命令？
- 退出码是多少？
- 标准输出和错误输出分别是什么？
Qoder CN 的终端面板会透明展示 Agent 的执行过程。如果你没看到——在对话里让 Agent 把完整错误信息发给你。
第二步：自己手动跑一次
同样的命令，在系统终端（Windows Terminal / macOS Terminal / iTerm）里自己跑一遍：
| 结果 | 说明 |
|---|---|
| 手动能跑通 | Agent 的环境和你的环境不一样——看第四步 |
| 手动也报错 | 命令本身或环境有问题，跟 Qoder 无关 |
第三步：检查权限
Qoder CN 执行命令时有几种权限级别：
| 模式 | 说明 |
|---|---|
| 手动确认 | 每次 Agent 执行命令都等你点确认 |
| 自动放行部分 | 配置了某些命令自动放行（如 npm install） |
| 完全自动 | 放行所有命令（需谨慎） |
如果 Agent 总是卡在等你确认——是权限设置的正常行为，不是 bug。
如果 Agent 被拒绝但你认为应该放行——去设置里调整自动放行范围。
第四步：环境差异排查
Agent 执行命令的环境和你手动打开的终端可能不同：
| 差异点 | 检查 |
|---|---|
| PATH | Agent 的 PATH 和你的终端 PATH 一样吗？让 Agent 跑 echo %PATH%（Windows）或 echo $PATH（macOS） |
| 工作目录 | Agent 在哪个目录下跑的命令？对吗？ |
| Node.js / Python / Go 版本 | 让 Agent 跑 node --version / python --version，看版本对不对 |
| 虚拟环境 | Python venv / conda env 有没有激活？Node 的 nvm 环境有没有生效？ |
| 环境变量 | 让 Agent 跑 env 或 set，看必要的环境变量（如 JAVA_HOME）有没有设置 |
第五步：常见命令失败场景
npm install 失败
| 可能原因 | 解决 |
|---|---|
| 网络问题（国内访问 npmjs 慢/被墙） | 配置国内镜像：npm config set registry https://registry.npmmirror.com |
| Node 版本太低 | 升级 Node.js |
| 权限问题 | 不要用 sudo npm install，用 nvm 或本地安装 |
| 依赖冲突 | 手动跑一次 npm install 看具体报错 |
pip install 失败
| 可能原因 | 解决 |
|---|---|
| 网络问题 | pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple |
| 虚拟环境没激活 | 让 Agent 先激活 venv 再 pip install |
| C 编译工具缺失 | Windows 装 Visual Studio Build Tools；macOS 装 Xcode Command Line Tools |
git 命令失败
| 可能原因 | 解决 |
|---|---|
| git 未安装 | 确认 git 在系统 PATH 里 |
| SSH key / Token 问题 | Agent 能不能访问远程仓库？ |
| 当前目录不是 git 仓库 | Agent 是不是在正确的目录下执行？ |
第六步：不要轻易用 Full Access
不要因为命令失败就把权限拉到 Full Access（完全自动）：
- 先搞清楚为什么失败；
- 修复根本原因（网络、环境、PATH）；
- 再调整放行范围。
Full Access 是最后的手段——风险很高，Agent 可能执行到你不想执行的命令。
下一步
- Agent 命令没问题但 MCP 调用失败 → MCP 服务常见问题
- Agent 还在卡住等你审批 → 手动确认或调整权限设置