AI Agent / 系统课时
排查权限与命令执行问题
排查权限与命令执行问题
Claude Code 出现“命令没执行”“同一命令在终端能跑、在会话里却失败”时,问题通常不在命令本身,而在权限规则、当前工作目录、进程环境或 Bash 沙箱。按层定位可以避免反复放宽权限,却始终没有修到真正的故障点。
学习目标
- 区分权限拒绝、Shell 环境错误与沙箱阻断三类执行失败
- 核对权限规则的来源、匹配顺序和当前工作目录
- 用最小化诊断命令验证 PATH、环境变量与隔离配置
先判断命令停在哪一层
排查时先看“命令是否真正启动”。如果 Claude Code 在调用 Bash 前就提示拒绝或要求确认,优先查权限规则;如果进程已经启动并返回 command not found、退出码或程序自身错误,转向 Shell 环境;如果出现只读文件系统、路径不可写、host not allowed 等限制,则继续查沙箱。

权限系统和沙箱是两层不同的控制。权限规则在工具执行前决定是否允许调用;沙箱在 Bash 进程已经运行后,由操作系统继续限制其文件和网络访问。因此“已经允许 Bash”并不等于进程可以写任意目录或访问任意域名。
核对实际生效的权限规则
Claude Code 的权限规则按 deny、ask、allow 的顺序匹配,前者优先。不同设置作用域中的权限列表会合并,所以某个项目里的 allow 不能覆盖用户或受管配置中的匹配 deny。先在 /status 确认本会话加载了哪些设置来源,再用 /permissions 查看权限配置;若怀疑 JSON 或规则写错,可运行 claude doctor 检查被拒绝的配置项。
下面是一个最小权限配置片段示例。它允许测试命令直接运行,对推送操作始终询问,并禁止读取常见环境文件:
{
"$schema": "https://json.schemastore.org/claude-code-settings.json",
"permissions": {
"allow": [
"Bash(npm run test *)"
],
"ask": [
"Bash(git push *)"
],
"deny": [
"Read(./.env)",
"Read(./.env.*)"
]
}
}生效行为是:匹配测试命令时可免确认,匹配 git push 时仍需确认,而 .env 读取被阻止。保存后应在 /status 看到对应设置来源已加载,并在 /permissions 中核对规则;若项目尚未被信任,共享项目中的部分允许规则可能暂不生效。
验证工作目录与 Shell 环境
Claude 默认从启动会话的目录工作,之后 /cd 会改变主工作目录。相对路径、项目级设置、脚本位置以及某些工具的配置文件都会因此改变。若“文件明明存在”却找不到,先核对当前目录,再确认 Claude Code 子进程实际看到的 PATH。
在 macOS、Linux 或 WSL 中,可让 Bash 执行下面的诊断命令:
printf 'cwd=%s\n' "$PWD"
printf 'shell=%s\n' "${SHELL:-<unset>}"
printf 'path=%s\n' "$PATH"
command -v claude || true预期输出
cwd=<PATH>
shell=<PATH>
path=<VALUE>
<PATH>/claude实际路径会因机器而异。如果最后一行缺失,说明当前 Bash 环境无法通过 PATH 找到 claude;如果 cwd 不是预期项目目录,应先修正会话工作目录,而不是继续修改权限。项目需要固定环境变量时,可放入受控的设置 env 块,但仍要先确认是否有更高优先级配置或启动环境覆盖相关值。
检查沙箱而不是继续放宽权限
当命令已启动,却只能在 Claude Code 内失败时,沙箱是重点。启用沙箱后,Bash 默认可写当前工作目录、已添加目录和会话临时目录;写其他位置需要 sandbox.filesystem.allowWrite。网络访问则受允许域名控制,因此 CLI 访问新主机时可能被阻断。
优先缩小例外范围:只为确实需要的路径增加 allowWrite,只加入必要的网络域名。某些工具若明确无法在沙箱内运行,可以评估 excludedCommands,但这意味着该命令绕过隔离,风险明显高于增加单个路径或域名。若组织设置了 allowUnsandboxedCommands: false,Claude Code 也不会把失败命令自动重试为非沙箱执行。
用证据闭环验证修复
修复后不要只看“提示消失”,而要重跑原始命令并确认三件事:权限不再意外阻断、进程使用正确目录与环境、沙箱没有新的文件或网络拒绝。如果问题仍不稳定,可开启 Claude Code 的 debug 日志并写入明确路径,把权限、Hook 和工具执行相关信息保留下来,再围绕第一次失败前后的记录定位。
排查这类问题的关键不是一次性提高权限,而是确认失败发生在哪一层。权限、工作目录、Shell 环境和沙箱各自有独立职责,只有把故障落到具体边界,修改才可验证、可回滚,也不会顺手扩大整个项目的执行能力。