工作区

工作区提供了一种在组织内组织 API 使用情况的方式。使用工作区可以分隔不同的项目、环境或团队，同时保持集中的计费和管理。

工作区的工作原理

每个组织都有一个默认工作区（Default Workspace），它无法被重命名、归档或删除。当您创建额外的工作区时，可以为每个工作区分配成员、服务账户、API 密钥和资源限制。

主要特征：

• 工作区标识符使用 wrkspc_ 前缀（例如 wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ）。
• 默认情况下，每个组织最多 100 个工作区（已归档的工作区不计入）。如果您需要更多，请联系您的客户团队。
• 默认工作区与其他工作区一样拥有 wrkspc_ ID（在 anthropic-workspace-id 响应头中返回，并被获取工作区可查看包含 API 参考文档链接的预览——按 Tab 键直到焦点进入卡片，按 Escape 键返回。接受），但只有当您传递 include_default=true 时，它才会出现在列出工作区可查看包含 API 参考文档链接的预览——按 Tab 键直到焦点进入卡片，按 Escape 键返回。的结果中。用量和成本分析 API 会在该 ID 下报告其用量和成本，而旧版用量和成本 API 的报告中其 workspace_id 显示为 null（对于绑定到默认工作区的密钥，API 密钥的 scope 字段包含真实 ID）。
• API 密钥可以限定到单个工作区。在这种情况下，它们只能访问该工作区内的资源。其他 API 密钥不限定到工作区。使用这类密钥时，请在每个请求中发送工作区 ID 请求头来选择工作区。该密钥的用户或服务账户必须有权访问该工作区。

Claude Code 工作区

当您组织的成员首次使用其 Claude Console 账户登录 Claude Code 时，Anthropic 会自动在组织中创建一个 Claude Code 工作区并将该成员添加到其中。之后每个登录 Claude Code 的成员都会以相同方式被添加。

Claude Code 工作区将 Claude Code 流量与您的其他 API 工作负载分隔开：

• Claude Code 在登录时在此工作区中铸造一个按用户的 API 密钥。您无法从 Console 手动在其中创建密钥。
• 与工作区密钥不同，如果 Claude Code 密钥的所有者被从工作区或组织中移除，该密钥将停止工作。
• Claude Code 的用量单独进行速率限制，管理员可以在 Claude Console 中的速率限制下限制其在组织限制中所占的份额。
• 它是唯一支持按用户每月支出限制的工作区。

工作区角色和权限

成员可以在每个工作区中拥有不同的角色，从而实现细粒度的访问控制。

角色继承

• 组织管理员自动获得所有工作区的工作区管理员访问权限。
• 组织计费成员自动获得所有工作区的工作区计费访问权限。
• 组织用户和开发者必须被显式添加到每个工作区。
• 服务账户在 Claude Console 的服务账户页面（platform.claude.com/settings/service-accounts）上添加到工作区：在账户的菜单中或其自身页面上选择添加到工作区。要查看某个工作区中的账户，请按工作区筛选列表。

管理工作区

使用 Console

在 Claude Console 的工作区页面上创建和管理工作区。

创建工作区

1. 1

   打开工作区设置

   在 Claude Console 中，前往工作区页面（platform.claude.com/settings/workspaces）。

2. 2

   打开创建工作区页面

   点击创建工作区，打开 Console 中的创建工作区页面（platform.claude.com/settings/workspaces/new）。

3. 3

   配置工作区

   输入工作区名称并选择一种颜色以便于视觉识别。

4. 4

   创建该工作区

   点击创建工作区完成创建。

编辑工作区详情

要修改工作区的名称或颜色：

1. 从列表中选择工作区。
2. 打开更多操作菜单（三个点）并选择编辑详情。
3. 更新名称或颜色并保存您的更改。

向工作区添加成员

1. 在 Claude Console 中，前往成员页面（platform.claude.com/settings/members）。
2. 点击添加到工作区。
3. 选择工作区、要添加的组织成员及其工作区角色。
4. 点击添加到工作区确认。

从工作区移除成员

1. 在 Claude Console 的成员页面上，从工作区下拉菜单中选择工作区。如果显示为全部，则移除成员会改为将该成员从您的组织中移除。
2. 在该成员所在行的末尾，打开更多操作菜单（三个点）并选择移除成员。
3. 点击移除确认。

设置工作区限制

您需要在不同的位置设置工作区的速率限制和支出限制：

• 速率限制： 在 Claude Console 中的速率限制下，从工作区下拉菜单中选择工作区，然后点击模型旁边的编辑，设置每分钟请求数、输入令牌或输出令牌的限制。
• 支出限制：在 Claude Console 的工作区页面上，选择工作区。在打开的面板中，点击支出限额以限制每月支出，并配置支出达到特定阈值时的提醒。

归档工作区

要归档工作区，请打开其更多操作菜单（三个点）并选择归档工作区。归档操作：

• 保留历史数据以供报告使用
• 停用工作区并归档为其创建的每个 API 密钥
• 无法撤销

使用 Admin API

使用 Admin API 以编程方式管理工作区。

以下 SDK 和 CLI 示例构造默认客户端，该客户端从 ANTHROPIC_API_KEY 环境变量读取 Admin API 密钥；SDK 在 client.organization.workspaces 下公开这些端点。SDK 的列表方法会按需获取后续页面，因此 limit 设置的是页面大小；PHP、Ruby 和 curl 示例只返回一页。

创建工作区：

client = anthropic.Anthropic()

workspace = client.organization.workspaces.create(name="Production")

print(f"id: {workspace.id}")
print(f"name: {workspace.name}")

列出工作区：

client = anthropic.Anthropic()

workspaces = client.organization.workspaces.list(limit=10, include_archived=False)

for workspace in workspaces:
    print(f"{workspace.id}: {workspace.name}")

归档工作区：

client = anthropic.Anthropic()

workspace = client.organization.workspaces.archive("wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ")

print(f"id: {workspace.id}")
print(f"archived_at: {workspace.archived_at}")

有关完整的参数详情和响应结构，请参阅工作区 API 参考可查看包含 API 参考文档链接的预览——按 Tab 键直到焦点进入卡片，按 Escape 键返回。。

管理工作区成员

向工作区添加成员：

client = anthropic.Anthropic()

member = client.organization.workspaces.members.add(
    "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
    user_id="user_01WxYzAbCdEfGhJkMnPqRsTu",
    workspace_role="workspace_developer",
)

print(f"user_id: {member.user_id}")
print(f"workspace_role: {member.workspace_role}")

更新成员的角色：

client = anthropic.Anthropic()

member = client.organization.workspaces.members.update(
    "user_01WxYzAbCdEfGhJkMnPqRsTu",
    workspace_id="wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
    workspace_role="workspace_admin",
)

print(f"user_id: {member.user_id}")
print(f"workspace_role: {member.workspace_role}")

从工作区移除成员：

client = anthropic.Anthropic()

removed_member = client.organization.workspaces.members.remove(
    "user_01WxYzAbCdEfGhJkMnPqRsTu",
    workspace_id="wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
)

print(f"user_id: {removed_member.user_id}")

有关完整的参数详情，请参阅工作区成员 API 参考可查看包含 API 参考文档链接的预览——按 Tab 键直到焦点进入卡片，按 Escape 键返回。。

API 密钥和资源限定

每个请求都在恰好一个工作区中运行，并且只能访问该工作区内的资源。具体是哪个工作区取决于密钥类型：

• 工作区密钥（没有所有者的旧式密钥）属于创建它的工作区，并始终在那里运行。
• 个人密钥或服务账户密钥以其用户或服务账户的身份执行操作。单工作区密钥始终在创建时选定的工作区中运行。未限定到工作区的密钥在每个请求的 anthropic-workspace-id 请求头所指定的工作区中运行。账户必须有权访问该工作区才能使用它。

限定到工作区的资源包括：

• 通过 Files API 创建的文件
• 通过 Batch API 创建的消息批次
• 通过 Skills API 创建的技能

某些资源的管理方式不同：

• MCP 隧道使用通过工作负载身份联合获得的 workspace:manage_tunnels OAuth 令牌进行管理，而不是 API 密钥。隧道在工作区中创建，Console 的 MCP 隧道列表和托管代理服务器选择器仅显示当前工作区中的隧道；10 个活动隧道的上限适用于整个组织。隧道管理需要具有隧道管理权限的角色；组织开发者可以查看但无法更改它们。
• 工作区本身和组织成员在组织级别通过 Admin API 进行管理，使用 Admin API 密钥、org:admin OAuth 令牌，或未限定到特定工作区的个人或服务账户密钥。

要查找组织的工作区 ID，请调用列出工作区可查看包含 API 参考文档链接的预览——按 Tab 键直到焦点进入卡片，按 Escape 键返回。端点（传递 include_default=true 以包含默认工作区），或在 Claude Console 的工作区页面上查找。

识别 API 响应背后的工作区

Claude API 响应在 request-id 和 anthropic-organization-id 响应头旁边包含一个 anthropic-workspace-id 头。其值是请求的 API 密钥或访问令牌解析到的工作区的 wrkspc_ 前缀 ID，包括当该工作区是默认工作区时。例如，成功的响应包含如下头：

HTTP/1.1 200 OK
request-id: req_018EeWyXxfu5pfWkrYcMdjWG
anthropic-organization-id: 0d0e7a3b-52f1-4c7e-9a51-3f6f2f7c1b9e
anthropic-workspace-id: wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ

当凭据未解析到工作区时（例如在 Admin API 请求上），或当请求在身份验证完成之前失败时（例如 401 错误），该头不存在。

以下示例发送一个 Messages API 请求并从响应头中读取工作区 ID：

client = anthropic.Anthropic()

response = client.messages.with_raw_response.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
workspace_id = response.headers.get("anthropic-workspace-id")
print(f"Workspace ID: {workspace_id}")

Workspace ID: wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ

相同的访问器也可以从其他 Claude API 端点读取该头，包括 Claude Managed Agents API。例如，从创建会话的响应中读取 anthropic-workspace-id，以记录该会话属于哪个工作区。

有了来自响应的工作区 ID，您可以：

• 确认该请求计入了哪个工作区的使用情况、成本和速率限制
• 将其与以下内容进行比对：用量和成本分析 API行中的 workspace_id 字段（对于默认工作区，这些行包含相同的 ID），以及 Admin API 中 API 密钥的 scope 字段，该字段包含密钥所绑定工作区的真实 ID，包括默认工作区
• 使用 Admin API 密钥将其传递给获取工作区可查看包含 API 参考文档链接的预览——按 Tab 键直到焦点进入卡片，按 Escape 键返回。，以检查它是否为您的默认工作区的 ID：默认工作区会返回 "name": "Default"，尽管除非您传入 include_default=true，否则列出工作区可查看包含 API 参考文档链接的预览——按 Tab 键直到焦点进入卡片，按 Escape 键返回。会省略它
• 在 Console 中打开该工作区以查找请求的资源，例如会话、文件、消息批次和技能

工作区限制

您可以为每个工作区设置自定义支出和速率限制，以防止过度使用并确保公平的资源分配。

设置工作区限制

您可以将工作区限制设置为低于（但不高于）您组织的限制：

• 支出限制：限制工作区的每月支出。要进行设置，请前往 Claude Console 中的工作区页面（platform.claude.com/settings/workspaces）并选择工作区。在打开的面板中，点击支出限额。
• 速率限制：限制每分钟请求数、每分钟输入令牌数或每分钟输出令牌数。要进行设置，请前往 Claude Console 中的速率限制，从工作区下拉菜单中选择工作区，然后点击模型旁边的编辑。

有关速率限制及其工作原理的详细信息，请参阅速率限制。您还可以使用速率限制 API 以编程方式读取当前组织和工作区的速率限制，并设置工作区速率限制。该 API 会存储高于组织限制的值，但仍会执行两者中较低的那个限制。

使用情况和成本跟踪

使用用量和成本分析 API按工作区跟踪使用量和成本：

client = anthropic.Anthropic()

rows = client.beta.organization.analytics.usage.list(
    starting_at="2026-09-01T00:00:00Z",
    ending_at="2026-09-08T00:00:00Z",
    time_bucket_width="1d",
    workspace_ids=["wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"],
    group_by=["workspace_id"],
)

for row in rows:
    print(f"{row.starting_at} {row.group.workspace_id}: {row.usage.total_tokens}")

默认工作区中的使用量和成本以默认工作区自身的 ID 进行报告。

常见用例

环境分隔

为开发、预发布和生产创建单独的工作区：

团队或部门隔离

将工作区分配给不同的团队以进行成本分配和访问控制：

• 具有开发者访问权限的工程团队
• 拥有自己 API 密钥的数据科学团队
• 对客户工具具有有限访问权限的支持团队

基于项目的组织

为特定项目或产品创建工作区，以分别跟踪使用情况和成本。

最佳实践

1. 1

   规划您的工作区结构

   在创建工作区之前，考虑您将如何组织工作区。考虑计费、访问控制和使用情况跟踪需求。

2. 2

   使用有意义的名称

   清晰地命名工作区以指示其用途（例如 “Production - Customer Chatbot” 或 “Dev - Internal Tools”）。

3. 3

   设置适当的限制

   配置支出和速率限制以防止意外成本并确保公平的资源分配。

4. 4

   定期审计访问权限

   定期审查工作区成员资格，以确保只有适当的用户才能访问。

5. 5

   监控使用情况

   使用用量和成本分析 API跟踪工作区级别的消耗。

常见问题

另请参阅

• Admin API
• Admin API 参考
• 速率限制
• 用量和成本分析 API和旧版用量和成本 API