这些问题来自控制沙箱可以访问和挂载哪些内容的治理规则，以及记录这些决策的审计日志。 有关 Docker Sandboxes 的其他问题，请参阅 故障排查。

命令因 "global network policy has not been initialized" 而失败

尚未设置网络预设，并且 CLI 无法提示你选择一个，因为它不在交互式终端中运行，例如在 CI 流水线或脚本中运行时。在设置预设之前，sbx run、sbx create 和 sbx exec 等操作 沙箱的命令都会返回此错误。请先设置预设：

$ sbx policy init balanced

可用值为 allow-all（Open）、balanced（Balanced）和 deny-all（Locked Down）。 有关更多细节，请参阅 不通过提示设置预设。

智能体无法安装软件包或访问 API

Docker Sandboxes 使用网络规则来控制出站流量。如果智能体 无法安装软件包或调用外部 API，那么该目标地址很可能不在允许范围内。检查哪些请求 被拦截：

$ sbx policy log

然后允许你的工作流需要的目标地址：

$ sbx policy allow network "*.npmjs.org,*.pypi.org,files.pythonhosted.org"

如果想改为允许所有出站流量：

$ sbx policy allow network "**"

如果 sbx policy allow 未能解除拦截，请参阅 本地允许规则没有效果。

沙箱的所有请求都被拦截

当策略强制执行无法获取有效的组织策略时，它会 fail closed，拦截所有网络请求和工作区 挂载，无论你的规则允许什么。被拦截的请求返回的消息会告诉你原因：

• Denied because governance could not be resolved：运行 sbx policy ls。如果状态行 显示 Governance: Unresolved，请参阅 sbx policy ls 显示 Governance: Unresolved。
• Denied because the policy snapshot is stale：守护进程失去了与治理服务的连接，或者 你的 Docker 会话已过期。检查你的网络连接，如果问题仍然存在，运行 sbx login 重新登录。

本地允许规则没有效果

如果你添加了本地允许规则之后某个目标地址仍被拦截，那么很可能是为你强制执行了组织 策略。运行 sbx policy ls 并在状态行中查找 Governance: Managed by <org>。当为你 强制执行组织策略时，本地允许规则处于非活动状态，无法放宽组织策略所允许的范围。

要确认这一点，运行 sbx policy ls --wide --include-inactive，并检查你的规则在 STATUS 列中显示为 inactive。

如果你需要访问其他目标地址，请联系管理员更新组织策略。有关更多细节，请参阅 组织策略如何与本地规则和 Kit 规则相互关联。

sbx policy ls 显示 Governance: Unresolved

Docker 无法确定哪个组织治理你的账户。例如，当你的账户同时属于多个启用治理的组织时， 就会发生这种情况。状态行下方的 Details 行会说明原因。

在冲突解决之前，策略强制执行会 fail closed，因此本地允许规则无法授予访问权限。请 联系相关组织的管理员解决冲突的治理配置。

请求因 "Approval required" 被拦截

该目标地址需要你的确认。要么没有任何允许或拒绝规则与之匹配，且没有为你强制执行组织 策略；要么组织策略允许该地址，但要求先获得审批。

运行 sbx policy approval ls 查看待处理的请求，并用 sbx policy approval respond 进行回应。批准会应用于后续请求，而不是被拦截的那一个，因此之后需要重新运行该操作。 有关更多细节，请参阅 回应审批请求。

已允许的主机上的某个 HTTP 方法或路径被拦截

主机规则允许的目标地址，其单个方法或路径仍可能被 HTTP 规则拒绝。运行 sbx policy ls --type http 查看哪些 HTTP 规则适用。sbx policy check network 只 报告主机的判定结果，因此即使具体请求被拒绝，它也会显示该主机为允许。有关更多细节， 请参阅 允许或阻止 HTTP 方法和路径。

沙箱无法挂载其工作区

如果沙箱挂载失败并出现 mount policy denied 错误，那么要么是组织文件系统策略不允许 该路径，要么是 Docker Sandboxes 无法解析该路径。

如果沙箱的工作区在守护进程上次加载该沙箱时、或沙箱上次尝试启动时被拒绝，sbx ls 会在其工作区之后显示 (blocked by policy)。策略变更同步后该标签不会更新。被拦截的 沙箱在策略允许该路径之前无法启动，但你可以用 sbx rm 删除它。

当策略拒绝该路径时，开发者机器上的 sbx 命令会返回一个错误，其中列出每个被拒绝的 路径、被拒绝的访问以及原因。例如，如果名为 block-ssh 的拒绝规则拒绝了对 ~/.ssh 的只读挂载，错误为：

mount policy denied: /Users/dev/.ssh: fs:mount:read denied: denied: rule "block-ssh" matched op(action=fs:mount:read, resource=fs:path:/Users/dev/.ssh)

部分	示例	描述
路径	/Users/dev/.ssh	用于比对规则的解析后路径
访问	fs:mount:read denied	被拒绝的是哪种访问。可写挂载若缺少其中之一，则会分别列出 fs:mount:read 和 fs:mount:write
原因	denied: rule "block-ssh" matched ...	匹配的拒绝规则。未命名的拒绝规则显示为 rule ""。当没有允许规则覆盖该路径时，原因以 no allow rule matched 开头

管理员可以在审计日志中找到相同的判定，其记录的动作类型为 filesystem_mount。有关更多 细节，请参阅 动作类型。

检查以下常见原因：

原因	挂载被拒绝的原因	修复方式
允许规则使用 * 而不是 **	单个 * 只匹配一个路径段，因此 ~/* 匹配 ~/project，但不匹配 ~/project/src	使用 ** 匹配整个目录树，例如 ~/**
工作区可写，但策略只允许 read	可写工作区同时需要 read 和 write	在规则中添加 write
规则使用了 %USERPROFILE% 或 $HOME 之类的环境变量	策略引擎只展开 ~，因此该变量会按字面文本匹配	把变量替换为 ~，例如 ~/**
规则使用了另一种操作系统的路径格式	macOS 或 Linux 路径（例如 /data/**）不匹配 Windows 路径（例如 C:\data），也不匹配以 \\wsl.localhost\<distro>\ 开头的 WSL 路径	添加一条采用开发者操作系统格式的规则
规则的大小写与 macOS 或 Linux 路径不一致	macOS 和 Linux 路径区分大小写，因此 ~/Projects/** 不匹配 ~/projects/app	与磁盘上目录名的大小写保持一致
工作区是一个符号链接，指向没有任何规则允许的目录	策略检查的是链接指向的目录，而不是链接本身	允许该链接的目标目录，或直接挂载目标目录

有关路径的书写和匹配方式，请参阅 文件系统挂载规则语法。

组织策略变更没有生效

管理员更新组织策略之后，变更最多需要 5 分钟才能到达开发者的机器。要在开发者机器上 立即应用变更，运行 sbx policy refresh。它会获取并应用最新的组织策略，而不重启守护 进程，也不停止正在运行的沙箱。

刷新后的策略只应用于新的连接。如果某个连接是沙箱在此前的策略允许时建立的，那么即使 新策略拒绝了它，该连接仍会保持打开。重启沙箱即可关闭这些连接。

同步的变更何时生效还取决于策略类型。有关更多细节，请参阅 策略变更何时到达开发者。

审计记录缺失

如果某个组织的审计日志中没有来自开发者的记录，请检查以下内容：

• 该开发者处于治理之下。只有已登录、持有 AI Governance 许可证且受已强制执行的组织 策略治理的用户才会产生记录。在开发者的机器上运行 sbx policy ls，并在状态行中查找 Governance: Managed by <org>。
• 该开发者运行的是 Docker Sandboxes 0.39.0 或更高版本。运行 sbx version 检查，并在 需要时安装更新的版本。
• 云端交付已开启。记录只能通过云端交付进入 Docker Home 中的审计事件和 SIEM 流式 传输。在托管审计日志出现之前使用本地审计日志的组织，初始状态下云端交付是关闭的。 有关更多细节，请参阅 配置审计交付。
• 本地文件已定稿。在本地交付模式下，守护进程先把记录写入 .tmp 文件，在 5 分钟、 1000 个事件、50 MiB 之后，或者在守护进程正常关闭时，将其重命名为 .jsonl。有关 更多细节，请参阅 记录存储在哪里。