故障排除

Table of contents
Availability: Experimental
Requires: Docker Desktop 4.50 or later

本指南帮助您解决在本地为 Claude Code 创建沙箱时的常见问题。

'sandbox' 不是一个 docker 命令

当您运行 docker sandbox 时，会看到一条提示该命令不存在的错误。

这意味着 CLI 插件未安装或未位于正确的位置。要解决此问题：

  1. 验证插件是否存在：

    $ ls -la ~/.docker/cli-plugins/docker-sandbox

    该文件应该存在并且是可执行的。

  2. 如果使用 Docker Desktop，请重启它以检测该插件。

需要由您的管理员启用“实验性功能”

在尝试使用沙箱时，您看到一条关于 Beta 功能被禁用的错误。

当您的 Docker Desktop 安装由锁定了设置的管理员管理时，会发生这种情况。如果您的组织使用了 设置管理，请要求您的管理员 允许 Beta 功能：

{
  "configurationFileVersion": 2,
  "allowBetaFeatures": {
    "locked": false,
    "value": true
  }
}

身份验证失败

Claude 无法进行身份验证，或者您看到 API 密钥错误。

API 密钥可能无效、已过期或未正确配置。解决方法取决于您的凭证模式：

如果使用 --credentials=sandbox（默认模式）：

  1. 移除已存储的凭证：

    $ docker volume rm docker-claude-sandbox-data

  2. 启动一个新的沙箱并完成身份验证工作流：

    $ docker sandbox run claude

工作区包含 API 密钥配置

启动沙箱时，您会看到一条关于凭证冲突的警告。

当您的工作区中包含一个带有 primaryApiKey 字段的 .claude.json 文件时，会发生这种情况。请选择以下方法之一：

  • 从您的 .claude.json 中移除 primaryApiKey 字段：

    {
  "apiKeyHelper": "/path/to/script",
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.anthropic.com"
  }
}

  • 或者在出现警告的情况下继续 - 工作区凭证将被忽略，优先使用沙箱凭证。

访问工作区文件时权限被拒绝

当访问工作区中的文件时，Claude 或命令因“权限被拒绝”错误而失败。

这通常意味着工作区路径无法被 Docker 访问，或者文件权限过于严格。

如果使用 Docker Desktop：

  1. 在 Docker Desktop → 设置 → 资源 → 文件共享 中检查文件共享设置。

  2. 确保您的工作区路径（或其父目录）已列在虚拟文件共享下。

  3. 如果缺失，点击“+”添加包含您工作区的目录。

  4. 重启 Docker Desktop。

对于所有平台，请验证文件权限：

$ ls -la <workspace>

确保文件是可读的。如果需要：

$ chmod -R u+r <workspace>

同时验证工作区路径是否存在：

$ cd <workspace>
$ pwd