Claude API IP 白名单配置教程：防止 API Key 泄露被盗用

Claude API IP 白名单配置教程：API Key 泄露了也只能在你的服务器上用

2026 年 11 月 5 日，Anthropic 在 Claude Developer Platform 上线 IP 白名单（IP allowlisting，beta）。组织管理员可以限制 Claude Console 和 Messages 等 API 只接受白名单 IP 发来的请求。就算 API Key 被误提交到 GitHub 或被人盗走，攻击者不在白名单网络里也用不了。本文手把手讲 Claude API IP 白名单怎么配、怎么验证，以及怎么避免把自己锁在外面。

Claude API IP 白名单能帮你做到什么

配置完成后：

• API 请求受限：使用 API Key 或 WIF token 调用 Messages、Message Batches、Token Counting、Models、Files、Skills 等接口时，非白名单 IP 会被拒绝。
• Managed Agents 接口受限：Agents、Sessions、Environments、Vaults、Memory stores 接口同样受管控（只管调用这些接口的请求，不管 Agent 运行时的网络）。
• Console 受限：非白名单网络无法打开 Claude Console。
• 组织 API 受限：Admin API 和 Compliance API（使用只覆盖本组织的 Key 时）也在范围内。

官方建议把 IP 白名单和短有效期 Key 或 Workload Identity Federation 搭配使用：白名单限制 Key 在哪里能用，有效期限制 Key 能用多久。

[内链：Claude API Key 管理最佳实践]

前置条件

• 权限：Claude Platform 组织的 admin 或 owner。（Claude Enterprise 中只有 owner 和 primary owner 可以配置。）
• 公网出口 IP：服务器、CI、办公网络的公网出口地址。可以在对应机器上执行 curl https://ifconfig.me 查看。
• 费用：官方文档未提及额外收费，以官方最新说明为准。
• 注意 beta 状态：功能处于 beta，设置和行为可能调整。

分步骤配置 IP 白名单

第 1 步：整理要放行的地址

把所有会调用 Claude API 的出口地址列出来：生产服务器、预发环境、CI 运行器、开发者办公网络或公司 VPN 出口。规则如下：

官方特别提醒：共享代理的出口地址也可能被持有泄露 Key 的攻击者使用，尽量不要放行公共代理。

第 2 步：在 Console 中添加条目

1. 打开 Claude Console 的 Identity and access 页面；
2. 打开 IP allowlist 开关；
3. 点击 Add entry，输入地址或网段，多个用逗号分隔，按回车；
4. 点击 Save 并确认。不点保存不会生效。

第 3 步：勾选管理员例外，防止锁死

保存时页面只检查你当前的地址，不会检查服务器、同事、CI 或以后的网络。建议勾选 Allow admins to access this settings page from any IP address，这样管理员在任何网络下都能进入设置页修正名单。

代价是：如果管理员会话被盗，攻击者也能远程修改名单。名单变更会记录在 Compliance API 的 Activity Feed 中，可以用于审计。

第 4 步：等待生效并验证

变更最多需要 15 分钟生效。之后分别在白名单内和白名单外的机器上验证。

cURL 验证（用不消耗 token 的 Models 接口）：

# 依赖：curl；先 export ANTHROPIC_API_KEY=你的 Key
curl -s https://api.anthropic.com/v1/models \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01"

白名单内的机器应正常返回模型列表；白名单外的机器应返回 HTTP 403，错误类型为 permission_error，信息为 “Your IP address isn't in this organization's allowed range.”

Python 验证：

# Python 3.9+，依赖：anthropic（pip install -U anthropic）
import anthropic

client = anthropic.Anthropic()  # 从环境变量 ANTHROPIC_API_KEY 读取 Key

try:
    models = client.models.list()
    print("allowed, first model:", models.data[0].id)
except anthropic.PermissionDeniedError as e:
    # 非白名单 IP 会返回 403 permission_error
    print("blocked:", e.status_code, e.message)

常见报错和解决方法

1. 开启后 CI 全部报 403 permission_error
GitHub Actions 等托管运行器的出口 IP 不固定。解决办法是改用固定出口 IP 的自托管运行器或 NAT 网关，再把该地址加入白名单。

2. 刚加了地址还是被拒
变更最多需要 15 分钟生效，稍后重试。同时确认填的是公网出口地址，而不是内网地址。

3. 管理员自己被锁在外面
按官方恢复步骤处理：先连回白名单内的网络或 VPN 后点击 Try again；或请白名单网络内的其他管理员添加你的地址；如果勾选过管理员例外，可以直接进入设置页点击 Add it 添加当前地址或关闭白名单；都不行时联系 Anthropic 支持关闭白名单。

4. 通过 Bedrock / Vertex / Foundry 调用的请求不受控
IP 白名单不适用于 Amazon Bedrock、Claude Platform on AWS、Claude Models on Google Cloud 和 Microsoft Foundry。这些渠道需要在各自云平台上做网络管控。

5. Enterprise 用户的 Cowork、Chrome 插件连不上
Claude in Chrome、Cowork、Remote Tools 和 Office 插件的部分功能通过 bridge.claudeusercontent.com 连接。如果它的出口 IP 与 claude.ai、api.anthropic.com 不同，需要把那个地址也加进来。

[内链：Anthropic API 错误码与排查]

同期上线的 Claude Enterprise 安全功能

同一天，Anthropic 还为 Claude Enterprise 推出一批安全和管理功能：

• 推理钩子（GA）：提示词钩子把提示词发给你的安全工具检查，工具调用前钩子在执行前检查工具调用，现有 DLP 策略可以作用到 Claude 上；
• 安全中心（beta）：对比组织设置与官方推荐配置，可导出报告给审计人员，官方强调这是指导建议，不是合规认证；
• 集中管理（beta）：在 admin.claude.com 统一管理 SSO、SCIM、域名验证等，设置后不可撤销；
• 访问控制（beta）：通过 Admin API 让成员在所有设备上退出登录而不移出组织等；
• Cowork EDR（beta）：在 macOS 和 Windows 的 Cowork 虚拟机里运行 EDR 探针，仅检测、不拦截。

使用建议

• 小团队：先放行生产服务器和办公网络出口，勾选管理员例外，观察一周再收紧。
• 有 CI 的团队：先解决 CI 固定出口 IP 的问题，再开启白名单。
• 多环境：用 CIDR 网段代替逐个 IP，但不要放得太宽。
• 定期审计：结合 Activity Feed 记录名单变更，与 Key 轮换一起排进安全检查清单。

总结

Claude API IP 白名单解决的是 API Key 泄露后的止损问题：Key 被盗也只能在你的网络里用。配置本身只需要几分钟，真正要花时间的是梳理出口 IP 和处理 CI 等动态地址。功能目前是 beta，具体覆盖范围和行为以 Anthropic 官方最新文档为准。

常见问题

Claude API IP 白名单怎么设置？
组织 admin 或 owner 进入 Claude Console 的 Identity and access 页面，打开 IP allowlist，添加地址或 CIDR 后点击 Save 确认，最多 15 分钟生效。

Claude API IP 白名单收费吗？
官方文档未提及额外收费，功能目前为 beta。

Claude API 返回 403 permission_error 是什么原因？
如果信息是 “Your IP address isn't in this organization's allowed range.”，说明请求来源 IP 不在组织的白名单内，需要把出口 IP 加入白名单。

通过 AWS Bedrock 调用 Claude 受 IP 白名单影响吗？
不受影响。IP 白名单不适用于 Amazon Bedrock、Claude Platform on AWS、Google Cloud 和 Microsoft Foundry 渠道。

IP 白名单最多能加多少条？
每个组织最多 1,000 条，支持 IPv4、IPv6 和 CIDR 网段。

参考来源

• Claude Platform 更新日志（2026-11-05）
• Claude 文档：IP allowlisting（访问于 2026-11-08）
• Claude Enterprise security updates（2026-11-05）