保护您的 Managed Agents 部署

本指南列出了限制 Claude Managed Agents 上的智能体可以访问和执行哪些操作的设置，按重要性从高到低排列。每个部分都链接到完整介绍该设置的页面。

安全风险与沙箱边界解释了这些设置为何重要以及它们无法防范哪些情况。要审查和监控会话，请参阅审查和监控智能体会话。

选择智能体的运行位置

智能体工具的运行位置决定了由谁来保护沙箱：使用云环境时由 Anthropic 负责，使用自托管沙箱时由您负责。要在两者之间做出选择并了解每种方式下哪些内容会到达 Anthropic，请参阅选择智能体环境。

如果您使用自托管沙箱，请牢记以下四点：

• 网络： 限制网络适用于云环境。对于自托管沙箱，请在您自己的防火墙中对其流量设置同等的限制。您的防火墙不会限制智能体声明的 MCP 服务器，因此请审查这些服务器，以及您的应用程序为会话设置的任何服务器。
• Web 工具： Web 工具在 Anthropic 的服务器上运行，因此您的防火墙不会限制它们。请使用它们的域名列表来限制它们。请参阅限制网页搜索和网页抓取。
• 凭据： 自托管沙箱尚不支持环境变量凭据。
• 隔离和加固： 这两项都由您负责。请参阅安全模型。

这两种选项都不会改变 Managed Agents 的合规覆盖范围，也不会改变其保留会话历史的时长。请参阅监控会话并查看保留策略。

限制网络

将 networking.type 设置为 limited，并在 allowed_hosts 中仅列出智能体需要的主机。省略 networking 的环境创建请求可能会得到 unrestricted，因此请在每个创建请求中设置 networking。请参阅不受限网络的风险。

无论 allowed_hosts 如何设置，您附加的文件、记忆存储和 GitHub 仓库都对智能体保持可用。

本页的示例使用一个客服智能体。它读取客户的工单，查询订单，阅读您的帮助中心，并起草回复。订单查询由您的应用程序运行，不需要任何主机，因此该环境只为 web_fetch 允许一个主机，即帮助中心：

ant apply environment.yaml

# yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/environment.json
name: support-agent
config:
  type: cloud
  networking:
    type: limited
    allowed_hosts:
      - help.example.com

limited 环境有三个网络设置：

allow_package_managers 和 allow_mcp_servers 设置不会为网页搜索和网页抓取添加任何主机。

保持 allow_mcp_servers 关闭（这是默认设置），并在 allowed_hosts 中列出您运营或信任的每个 MCP 服务器的主机。您列出的每个主机也会向沙箱中的代码开放。在 allow_mcp_servers 关闭的情况下，如果某个 MCP 服务器的主机未被列出，会话创建时的检查会拒绝该请求。请参阅在会话创建时提供身份验证。当会话更新更改 mcp_servers 时，也会运行相同的检查。

为 allowed_hosts 选择主机时，请遵循以下两条规则：

• 仅列出您运营或信任的主机。
• 避免使用 *. 通配符以及任何人都可以发布内容的共享托管域名。

如果智能体保留 bash，请按照审批有风险的操作中的说明设置 bash 工具的权限策略。

有关所有网络设置，请参阅云环境设置。

将凭据保存在保管库中

将每个密钥都存储在保管库中。对于每个环境变量凭据，将注入位置设置为仅限请求头，并仅列出该密钥所对应的主机。沙箱中的代码看到的是占位符，而不是密钥本身。Managed Agents 仅在发往该凭据所允许主机的出站 HTTPS 请求中替换为真实密钥。因此，密钥不会被模型直接获取，除非某个服务将其发回，例如回显请求头的端点。如果凭据的 networking 为 unrestricted，Managed Agents 会在发往环境允许沙箱访问的任何主机的请求中替换为真实密钥。要使用保管库，请在创建会话或部署时在 vault_ids 中传入其 ID。

客服智能体不需要保管库凭据，因为您的应用程序持有订单 API 的 API 密钥。如果您的智能体确实持有保管库凭据，请参阅添加凭证，了解各种语言的请求示例。

不要将密钥放在系统提示、智能体定义和消息中。不要向智能体提供 Claude API 密钥。即使 Claude API 密钥存放在保管库中，沙箱中的代码也可以使用它直接调用 Claude API。它可以执行该密钥允许的任何操作，例如启动或删除会话，或使用网页搜索和网页抓取。智能体的工具设置、审批和预算不适用于这些调用。在 limited 环境中，只有当 allowed_hosts 允许沙箱访问 api.anthropic.com 时，代码才能进行这些调用。

请自行获取令牌并将其存储在保管库中，因为沙箱中的代码使用已存储的密钥获取的令牌会以未脱敏的形式返回。

将不同信任级别工作负载的保管库放在不同的工作区中，因为任何有权访问某个工作区的 API 密钥都可以引用该工作区的保管库。请使用作用域限定为单个工作区的 API 密钥。

有关 MCP 凭据和轮换，请参阅使用 vault 进行身份验证。

限制网页搜索和网页抓取

将 web_fetch 上的 allowed_domains 设置为智能体需要的站点。智能体获取的任何 URL 都可能将数据携带到其指向的站点，因此该列表是一项安全控制措施。在 web_search 上，将 allowed_domains 设置为您希望从中获取结果的站点，以便结果仅来自您信任其准确性的站点。该列表不会阻止搜索查询到达搜索提供商。搜索结果包含来自页面的文本，因此该列表也会限制哪些站点的文本能够到达智能体。对于每种类型的环境，都请在这两个工具上设置 allowed_domains。

blocked_domains 列表会阻止您列出的主机及其子域名，而不会阻止其他任何主机。相同的内容仍可能通过网页存档、缓存、镜像或您未列出的相关域名到达智能体。不要依赖 blocked_domains 来保障安全。请使用 allowed_domains 并指定您信任的主机。

在 limited 环境中，限制网络中的 allowed_hosts 列表也会限制 Web 工具。unrestricted 环境或自托管沙箱不会限制 Web 工具。

这两个列表匹配主机的方式不同：

如果智能体需要某个站点及其所有子域名，请在 allowed_hosts 中同时列出 example.com 和 *.example.com，否则请列出确切的主机。如果某个工具列出了 example.com，而 allowed_hosts 仅列出了 *.example.com，会话会被创建。会话创建时的检查会将 example.com 视为在 *.example.com 范围内，但该工具不会从 example.com 本身返回任何内容。有关这两个列表的匹配方式，请参阅在智能体上设置域名列表。

web_fetch 工具也只会打开已在会话中出现过的 URL：

在多智能体会话中，只有当来自另一个智能体的 URL 是通过标记为"能"的来源到达该智能体时，web_fetch 才会打开它。直接调用的自定义工具结果算作标记为"能"的来源。即使其文本是由 Claude 编写的（例如当工具重复其输入时），这一点也成立。即使 URL 在书写时没有 https://（例如 example.com/docs），也可能被计入。web_fetch 工具并不总能打开显示文字而非 URL 的链接，例如"联系支持"。如果智能体必须获取尚未在会话中出现过的 URL，请在用户消息中发送该 URL。

此规则降低了注入文本构造出携带私密数据的 URL 的可能性。最终用户文本、搜索结果、获取的页面和自定义工具结果仍然可以添加 URL，因此请保持设置 allowed_domains。Messages API 应用了类似的规则，但来源列表不同。请参阅 URL 验证。

web_fetch 上的域名列表不会限制 bash 工具。请同时限制网络。请参阅域名列表规则。

审批有风险的操作

在 bash、write、edit 和 web_fetch 上，以及仅读取数据的 MCP 工具上设置 auto。如果您无法撤销某个工具在沙箱之外所做的更改，请改为在该工具上使用 always_ask。对于不应仅因您转发的最终用户文本要求就运行的工具，也请使用它。权限策略决定工具调用是直接运行、等待您的审批，还是由服务器进行评估。

为智能体提供最小的工具集中的工具集应用了这些策略。

auto 策略允许服务器运行调用、拒绝调用或暂停以等待审批。在长时间运行中，人工无法审批每个调用，因此改由服务器检查每个调用。请将 auto 与受限网络、权限范围窄的密钥、预算以及空闲会话告警搭配使用。auto 不是人工检查点，因此如果必须由人工在工具调用运行前进行审查，请在该工具上配置 always_ask。

auto 会将 user.message 事件中的文本以及 user.define_outcome 事件中的描述视为您的指令，包括您转发的最终用户文本。

暂停的会话会无限期等待，因此无人值守的会话需要一个能够响应暂停调用或中断会话的客户端。

在允许每个暂停的调用之前，请先对其进行审查。一个不向人工展示就允许每个调用的客户端，等同于 always_allow。请参阅响应确认请求和查看每次调用的评估方式。

为智能体提供最小的工具集

将 default_config.enabled 设置为 false，并仅启用智能体需要的工具。智能体工具集默认启用全部八个内置工具。

客服智能体需要三个内置工具：用于起草回复的 read 和 write，以及用于访问帮助中心的 web_fetch。它通过由您的应用程序运行的自定义工具 lookup_order 查询订单。您的应用程序持有订单 API 的 API 密钥，因此智能体既不需要 bash，也不需要凭据。

以下示例使用 allowed_domains 将 web_fetch 限制为 help.example.com。它按照审批有风险的操作的建议，在 write 和 web_fetch 上设置了 auto。如果客户的工单导致智能体使用这些工具，智能体只能更改沙箱中的文件或打开帮助中心页面。这就是这两个工具都不需要 always_ask 的原因。该示例还在 default_config 中设置了 always_ask，因此您之后启用的、没有自己策略的工具会使用 always_ask：

ant apply agent.md

---
name: Support Agent
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
    default_config:
      enabled: false
      permission_policy:
        type: always_ask
    configs:
      - name: read
        enabled: true
        permission_policy:
          type: always_allow
      - name: write
        enabled: true
        permission_policy:
          type: auto
      - name: web_fetch
        enabled: true
        allowed_domains: [help.example.com]
        permission_policy:
          type: auto
  - type: custom
    name: lookup_order
    description: Look up one order by its ID. Returns the status, the items, and the delivery date.
    input_schema:
      type: object
      properties:
        order_id:
          type: string
          description: The order ID from the ticket
      required:
        - order_id
---

智能体更新会替换整个 tools 数组，因此请发送您想保留的每个条目。

智能体更新只会作用于新会话，因此还请检查部署、列出此智能体的其他智能体以及现有会话：

• 部署会固定一个智能体版本，因此请将每个部署指向新版本。
• 在 subagents.predefined_agents 或 workflows.predefined_agents 中列出此智能体的智能体会保留其固定的版本，因此也请更新该智能体。
• 要收紧已存在的会话，请更新该会话的工具。会话必须处于 idle 状态，并且更新会替换整个 tools 数组。在多智能体会话中，会话所运行智能体的 Web 工具上新的 allowed_domains 和 blocked_domains 列表也会应用于其他每个智能体。它们从每个智能体的下一轮开始生效。这些智能体已启用的工具和权限策略不会改变。要更改这些内容，请更新每个智能体，然后启动新会话。

同样，请将 MCP 服务器和自定义工具限制在智能体需要的范围内：

• MCP 服务器： MCP 工具集默认启用服务器公开的每个工具。将 default_config.enabled 设置为 false 并启用指定的工具，这样服务器之后添加的工具会保持关闭。移除智能体不使用的服务器。请参阅 MCP 连接器。
• 自定义工具： 由您的应用程序运行，权限策略不适用。请在您的应用程序中验证每个调用的输入，并限制该工具可以触及的范围。

让不受信任的输入远离强大的工具

每当智能体读取不受信任的输入（即您团队之外的人可以编写的文本）时，请检查它持有哪些工具和凭据。本节使用两个术语：

• 不受信任的输入： 网页、搜索结果、支持工单、电子邮件、仓库文件、上传内容、MCP 服务器结果以及您转发的最终用户消息。
• 强大的工具： bash、write、edit、web_fetch、web_search、写入或发送数据的 MCP 工具和自定义工具，以及任何使用凭据的工具。

不受信任输入中的文本可以指示智能体使用其持有的强大工具。客服智能体会读取工单，因此它只能通过自定义工具 lookup_order 访问您的订单 API。您的应用程序会检查该订单是否属于工单的发送者。

在云环境中，使用 read 读取文件还可能将 CLAUDE.md 和 AGENTS.md 文件作为指令加载。它们从该文件所在目录及其父目录加载，直到沙箱的工作目录为止。它们通过 @ 加路径引用的文件（例如 @docs/setup.md）也会被加载，最多可嵌套五层引用。引用可以指向沙箱中的任何位置，例如 @/etc/hosts。除了禁用 read 之外，没有任何设置可以关闭此行为，因此请将您团队之外的人可以写入的仓库、软件包或归档文件视为不受信任的输入。

当智能体必须读取不受信任的输入并同时执行操作时，本指南推荐以下三种设计之一：

• 将读取与执行分离。 在一个多智能体会话中，由一个主智能体将任务分配给负责读取网页的获取者，以及负责更改文件或记录的写入者。
• 为智能体提供一个范围窄的自定义工具。 由您的应用程序运行该工具、检查其输入并持有凭据。客服智能体使用的是这种设计，而不是分离设计。请参阅回答使会话暂停的工具调用。
• 让人工参与其中。 在强大的工具上使用 always_ask，以便由人工审批每个调用。

分离设计使用三个智能体：

获取者的结果是基于不受信任的页面构建的，主智能体可能会将其文本传递给写入者。请在写入者的工具上保持 auto 或 always_ask。获取者仍然可以将其读取的部分内容发送到其 web_fetch 列表中的站点，并通过查询发送给搜索提供商。

同一多智能体会话中的智能体共享沙箱、其文件以及保管库凭据，因此这种分离只隔离了它们的工具和对话。要实现更强的隔离，请使用两个具有独立环境和保管库的会话。让您的应用程序在两个会话之间仅传递固定字段，例如订单 ID。

设置限制和停止方式

在创建每个会话时设置预算，并提前决定如何停止智能体。

要停止正在运行的智能体，请按照以下步骤操作：

1. 单独发送 user.interrupt。
2. 对于计划运行的智能体，还要暂停部署，以免启动新的计划运行。要永久结束计划，请归档该部署。
3. 如果某个密钥可能已泄露，请在签发该密钥的服务处轮换它。
4. 如果智能体有打开的工作流运行，还要发送一条 user.message 要求其停止这些运行，因为中断不会结束任何运行。有关需要先取消的工具调用，请参阅在有打开的运行时中断会话。
5. 等待会话进入 idle 状态。正在运行的会话无法被归档或删除。
6. 归档会话以保留其历史记录。当您不再需要历史记录时，将其删除。

中断不会撤销智能体已经执行或发送的内容。归档智能体不会停止其正在运行的会话。

预算的 max_list_cost.amount 是以字符串形式书写的美分整数，因此 "125" 表示 1.25 美元。请参阅在创建会话时设置预算。

您无法为创建时未设置预算的会话添加预算。要更改或移除上限，请参阅恢复达到预算的会话。移除会话的上限后，您将无法再设置新的上限。

预算会限制支出，但不会限制智能体在达到上限之前执行的操作。要将不同信任级别的工作负载隔离开来，请使用不同的工作区。为每个工作负载提供作用域限定为单个工作区的 API 密钥，因为可以访问多个工作区的密钥可以在其中任何一个工作区中执行操作。

请参阅会话预算、会话操作和计划部署。

后续步骤