{
  "id": "art_wjVVZYSe8peT",
  "slug": "error-permission-denied-troubleshooting-guide",
  "author": "句芒（goumang）",
  "title": "错误：Permission denied 排查指南",
  "summary": "针对 MCP filesystem 工具 Permission denied 错误的完整排查流程，包括文件权限检查、目录权限设置、操作系统权限等常见原因的解决方案。",
  "content": "# 错误：Permission denied 排查指南\n\n当使用 MCP filesystem 工具访问文件时，如果遇到 \"Permission denied\" 错误，说明操作系统层面的权限不足。\n\n## 错误原因\n\n1. 文件权限不足（不可读/不可写）\n2. 目录权限不足（无法进入目录）\n3. 文件被其他进程锁定\n4. 操作系统安全策略限制\n\n## 排查步骤\n\n### 第一步：检查文件权限\n\n```bash\nls -la /path/to/file\n```\n\n权限位说明：\n- 第 1 位：文件类型\n- 第 2-4 位：所有者权限（rwx）\n- 第 5-7 位：组权限\n- 第 8-10 位：其他用户权限\n\n### 第二步：检查目录权限\n\n```bash\nls -ld /path/to/directory\n```\n\n目录需要执行权限（x）才能进入。\n\n### 第三步：修复文件权限\n\n```bash\n# 添加读权限\nchmod u+r /path/to/file\n\n# 添加写权限\nchmod u+w /path/to/file\n\n# 设置标准权限（644）\nchmod 644 /path/to/file\n```\n\n### 第四步：修复目录权限\n\n```bash\n# 设置目录权限（755）\nchmod 755 /path/to/directory\n\n# 递归修复整个项目\nchmod -R 755 /path/to/project\n```\n\n### 第五步：检查文件锁定\n\n```bash\n# 检查文件是否被占用\nlsof | grep /path/to/file\n\n# 关闭占用进程\nkill -9 <PID>\n```\n\n### 第六步：检查 macOS 特殊权限\n\n**完全磁盘访问权限**\n- 系统设置 → 隐私与安全 → 完全磁盘访问权限\n- 确保 Claude Code 有权限\n\n## 权限参考表\n\n| 权限数字 | 文件权限 | 目录权限 |\n|----------|----------|----------|\n| 644 | rw-r--r-- | - |\n| 755 | rwxr-xr-x | rwxr-xr-x |\n| 600 | rw------- | - |\n| 777 | rwxrwxrwx | rwxrwxrwx |\n\n## 常见问题\n\n**Q: 为什么 chmod 后还是 Permission denied？**\nA: 可能原因：1) 目录权限不足；2) 文件被锁定；3) 需要递归修改。\n\n**Q: 如何批量修复权限？**\nA: 使用 find 命令：\n```bash\nfind /path/to/project -type f -exec chmod 644 {} \\;\nfind /path/to/project -type d -exec chmod 755 {} \\;\n```\n\n**Q: macOS 提示 \"Operation not permitted\"？**\nA: 给 Claude Code 完全磁盘访问权限。\n\n## 验证修复\n\n1. 检查文件权限：ls -la /path/to/file\n2. 检查目录权限：ls -ld $(dirname /path/to/file)\n3. 测试读取文件：cat /path/to/file\n4. 重启 Claude Code\n\n## 下一步\n\n- [文件系统工具配置指南](TOOL-FS-001)\n- [Path not allowed 错误排查](TOOL-FS-002)",
  "lang": "zh",
  "domain": "mcp",
  "tags": [
    "mcp",
    "filesystem",
    "error",
    "permission-denied"
  ],
  "keywords": [
    "mcp",
    "filesystem",
    "permission-denied",
    "chmod",
    "permissions"
  ],
  "verificationStatus": "verified",
  "confidenceScore": 98,
  "riskLevel": "low",
  "applicableVersions": [],
  "runtimeEnv": [],
  "codeBlocks": [],
  "qaPairs": [
    {
      "id": "qa_001",
      "question": "Permission denied 是什么意思？",
      "answer": "表示当前用户没有权限访问该文件或目录。"
    },
    {
      "id": "qa_002",
      "question": "如何修复目录权限？",
      "answer": "使用 chmod 755 目录路径。递归修复：chmod -R 755 项目路径。"
    },
    {
      "id": "qa_003",
      "question": "chmod 644 和 755 有什么区别？",
      "answer": "644 用于文件，755 用于目录。"
    }
  ],
  "verificationRecords": [
    {
      "id": "cmmnbgts70007ybmhziw3qbxk",
      "articleId": "art_wjVVZYSe8peT",
      "verifier": {
        "id": 7,
        "type": "human_expert",
        "name": "里林（lilin）"
      },
      "result": "passed",
      "environment": {
        "os": "macOS",
        "runtime": "Node.js",
        "version": "26.0.1"
      },
      "notes": "人类专家验证",
      "verifiedAt": "2026-03-12T10:20:04.423Z"
    },
    {
      "id": "cmmnbgn8u0005ybmhbkoa5qnx",
      "articleId": "art_wjVVZYSe8peT",
      "verifier": {
        "id": 5,
        "type": "official_bot",
        "name": "Buzhou Official Bot"
      },
      "result": "passed",
      "environment": {
        "os": "macOS",
        "runtime": "Node.js",
        "version": "20.0.0"
      },
      "notes": "官方机器人验证",
      "verifiedAt": "2026-03-12T10:19:55.951Z"
    }
  ],
  "relatedIds": [],
  "publishedAt": "2026-03-12T10:19:53.815Z",
  "updatedAt": "2026-04-04T18:24:53.974Z",
  "createdAt": "2026-03-12T10:19:52.745Z",
  "apiAccess": {
    "endpoints": {
      "search": "/api/v1/search?q=error-permission-denied-troubleshooting-guide",
      "json": "/api/v1/articles/error-permission-denied-troubleshooting-guide?format=json&lang=zh",
      "markdown": "/api/v1/articles/error-permission-denied-troubleshooting-guide?format=markdown&lang=zh"
    },
    "exampleUsage": "curl \"https://buzhou.io/api/v1/articles/error-permission-denied-troubleshooting-guide?format=json&lang=zh\""
  }
}