Claude Code 提示无法访问文件？排查权限、路径与工具调用

刚安装 Claude Code、配置好 API，执行初始化就提示没有访问文件系统的权限，很容易让人以为安装坏了或系统权限被锁死。实际排查时，这个现象通常落在两类原因上：一是 Claude Code 所在的进程确实看不到、不能读或不能写目标目录；二是模型或 API 端点没有正确执行工具调用，导致“读文件”这个动作根本没有发生。WSL、远程 Linux、第三方中转接口都会让两类问题混在一起。

更稳妥的顺序是：先确认它在哪里运行、以什么身份运行、目标文件是否存在，再验证接口是否支持 Claude Code 需要的工具调用。不要急着给目录 777 权限，也不要把报错文本直接当成最终结论。

先分清：是文件权限，还是工具调用没发生

Claude Code 访问文件通常不是靠“模型直接读磁盘”，而是由模型发起工具调用，再由运行 Claude Code 的本地或远程进程执行列目录、读文件、写文件等动作。如果模型只返回文字而没有发起工具调用，表现可能很像“没有权限”。

可以做一个最小验证：在终端进入项目目录，手动执行 pwd、ls -la，确认文件存在；再让 Claude Code 执行“请运行 pwd 和 ls -la，并把原始输出返回”这类任务。若它无法发起命令、只给解释，或者服务商日志里没有工具调用记录，优先怀疑模型或 API 端点；若命令能发起但系统返回 Permission denied，再回到文件权限排查。

本地与远程环境的排查清单

1. 确认工作目录

在运行 Claude Code 的同一个终端里执行：

pwd
ls -la
realpath .

确认当前目录就是项目根目录，而不是用户主目录或空目录。Claude Code 从哪个目录启动，通常就决定了它默认能看到哪些项目文件。项目在别处时，先 cd 过去再启动。

2. 确认运行身份和读写权限

whoami
id
ls -ld .
ls -l 目标文件
touch .write-test
rm .write-test

如果 touch 就失败，说明是操作系统层面的权限问题。常见情况包括目录属于其他用户、当前用户不在所属组、文件系统只读、容器挂载权限不对。处理时优先把项目放到当前用户可写的目录，或用最小范围的属主/属组调整解决，不建议直接 chmod 777。

3. WSL 与远程 Linux 的路径差异

在 WSL 中，Windows 盘符路径和 Linux 家目录不是一回事。项目放在 Windows 桌面，WSL 里未必在预期位置；先在 WSL 里用 ls 确认路径，再启动 Claude Code。路径映射不对时，看起来就像“文件不存在/没权限”。

在远程 Linux 服务器上，Claude Code 看到的是服务器上的文件，不是本地电脑上的文件。要确认代码已经克隆或同步到服务器，并且当前 SSH 用户对项目目录有读权限。若跑在容器里，还要检查 volume 是否挂载、是否只读挂载、容器用户与宿主机文件属主是否匹配。

4. 检查 Claude Code 自身的授权设置

首次进入某个项目时，Claude Code 可能会请求信任工作区、允许读取文件或执行命令。若曾经拒绝过，后续可能表现为无法访问文件。检查设置中当前项目是否在允许范围内，必要时重新授权。

授权范围建议控制在项目目录，不要为了省事长期开启全盘读写或无条件执行命令。这样既能减少误操作，也便于定位问题。

第三方中转 API 的常见坑

如果本地终端里文件权限完全正常，Claude Code 仍然读不到文件，就要重点看 API 端点。不是所有“兼容 Claude”的中转服务都完整支持 Claude Code 依赖的能力，例如工具调用、流式输出、系统提示词传递、较大的上下文和错误透传。模型名称看起来是较新的 Sonnet，并不代表端点一定转发了工具调用字段。

排查时可以看服务商控制台是否提供请求日志：一次读文件任务里有没有 tool_use 之类的工具调用记录，返回是否被截断，是否把工具定义丢掉。也可以用同一把 Key 做一个小型工具调用测试，观察返回是正常触发工具，还是只有普通文本。若只有文本，换官方 API 或明确支持工具调用的服务商对比即可。

选择中转服务时，建议按下面几项验证，而不是只看价格：

中转服务的取舍与风险

官方 API 或正规云服务通常在工具调用完整性、稳定性和数据责任上更可控，但可能涉及网络访问、成本和合规要求。第三方中转价格可能更低，适合临时测试，但要注意模型替换、请求日志留存、Key 泄露、服务突然不可用等风险。不要使用来源不明的共享账号、公开邀请码或把主账号 Key 直接贴进代码仓库；测试时使用独立 Key、设置额度，并避免把敏感代码发给不可信端点。团队和生产环境更建议走官方或合规的企业服务，具体可用性和条款以服务商最新说明为准。

环境因素与可选做法

如果排查后确认目录权限和接口工具调用都没问题，只是本地机器经常休眠、网络抖动，导致长时间任务中断，可以把运行环境放到长期在线的远程机器上。例如整台 Mac mini 托管在新加坡机房的独享远程 Mac，按月租用、远程连接使用，适合需要长期在线运行 Claude Code 等 AI 工具的场景。它属于环境优化，不能替代前面的权限和 API 兼容性排查。

小结

遇到 Claude Code 提示无法访问文件，先用手动命令验证操作系统权限，再检查 WSL/远程路径和 Claude Code 授权，最后验证 API 端点是否真正支持工具调用。中转服务可以试，但要用小任务验证兼容性，并控制密钥与代码数据的暴露范围。报错文本只是线索，按“运行位置—运行身份—接口能力”的顺序排查，通常比反复重装更快定位问题。