工作区

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

工作区的工作原理

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

主要特征：

• 工作区标识符使用 wrkspc_ 前缀（例如 wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ）
• 默认情况下每个组织最多 100 个工作区（已归档的工作区不计入）；如果您需要更多，请联系您的账户团队
• Default Workspace 与其他任何工作区一样拥有 wrkspc_ ID（在 anthropic-workspace-id 响应头中返回，并被 Get Workspace 接受），但它不会出现在 List Workspaces 的结果中，并且 API 密钥、使用报告和成本报告中其 workspace_id 显示为 null，全工作区 API 密钥也是如此（API 密钥的 scope 字段可以区分它们；对于绑定到 Default Workspace 的密钥，该字段携带真实 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 的使用量单独进行速率限制，管理员可以在设置 > 工作区下限制其占用组织限额的份额。
• 它是唯一支持按用户设置每月支出限额的工作区。

工作区角色和权限

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

角色继承

• 组织管理员自动获得所有工作区的 Workspace Admin 访问权限
• 组织计费成员自动获得所有工作区的 Workspace Billing 访问权限
• 组织用户和开发者必须被显式添加到每个工作区
• 服务账户可从设置 → 服务账户中的服务账户页面或从工作区的服务账户选项卡添加到工作区

管理工作区

使用 Console

在 Claude Console 中创建和管理工作区。

创建工作区

1. 1

   打开工作区设置

   在 Claude Console 中，前往设置 > 工作区。

2. 2

   创建工作区

   点击创建工作区。

3. 3

   配置工作区

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

4. 4

   创建该工作区

   点击创建以完成。

编辑工作区详情

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

1. 从列表中选择工作区。
2. 点击省略号菜单（...）并选择编辑详情。
3. 更新名称或颜色并保存更改。

向工作区添加成员

1. 导航到工作区的成员选项卡。
2. 点击添加到工作区。
3. 选择一位组织成员并为其分配工作区角色。
4. 确认添加。

要移除成员，请点击其姓名旁边的垃圾桶图标。

设置工作区限制

每个工作区的设置将这些限制分布在两个选项卡中：

• 速率限制：在速率限制选项卡上，按模型层级设置每分钟请求数、输入令牌数或输出令牌数的限制
• 支出限制：在支出限制选项卡上，限制每月支出并配置在支出达到特定阈值时的提醒

归档工作区

要归档工作区，请点击省略号菜单（...）并选择归档。归档操作：

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

使用 Admin API

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

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

创建工作区：

client = anthropic.Anthropic()

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

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

列出工作区：

client = anthropic.Anthropic()

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

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

归档工作区：

client = anthropic.Anthropic()

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

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

有关完整的参数详情和响应模式，请参阅工作区 API 参考。

管理工作区成员

向工作区添加成员：

client = anthropic.Anthropic()

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

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

更新成员的角色：

client = anthropic.Anthropic()

member = client.beta.organization.workspaces.members.update(
    "user_01XyDMpzjS89pFZXqSFUBDr6",
    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.beta.organization.workspaces.members.remove(
    "user_01XyDMpzjS89pFZXqSFUBDr6",
    workspace_id="wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
)

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

有关完整的参数详情，请参阅工作区成员 API 参考。

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，请调用 List Workspaces 端点，或在 Claude Console 中查找。

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

Claude API 响应在 request-id 和 anthropic-organization-id 响应头之外还包含一个 anthropic-workspace-id 响应头。其值是请求的 API 密钥或访问令牌所解析到的工作区的带 wrkspc_ 前缀的 ID，包括该工作区是 Default Workspace 的情况。例如，一个成功的响应包含如下响应头：

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",
    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 报告中以及 Admin API 对象（例如 API 密钥）上的 workspace_id 字段进行匹配（两者对于 Default Workspace 都报告 null，API 密钥对于全工作区密钥也是如此；API 密钥的 scope 字段可以区分这两者，并且对于绑定到单个工作区的密钥，该字段携带该工作区的真实 ID）
• 通过使用 Admin API 密钥将其传递给 Get Workspace 来检查它是否是您的 Default Workspace 的 ID：Default Workspace 会返回 "name": "Default"，即使 List Workspaces 省略了它
• 在 Console 中打开该工作区以查找该请求的资源，例如会话、文件、消息批次和技能

工作区限制

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

设置工作区限制

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

• 支出限制：限制工作区的每月支出。在 Claude Console 中工作区的支出限制设置选项卡上进行设置。
• 速率限制：限制每分钟请求数、每分钟输入令牌数或每分钟输出令牌数。在 Claude Console 中工作区的速率限制设置选项卡上进行设置。

有关速率限制及其工作原理的详细信息，请参阅速率限制。您还可以使用速率限制 API 以编程方式读取您当前的组织和工作区速率限制。

使用量和成本跟踪

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

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2025-01-01T00:00:00Z&\
ending_at=2025-01-08T00:00:00Z&\
workspace_ids[]=wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ&\
group_by[]=workspace_id&\
bucket_width=1d" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

归属于 Default Workspace 的使用量和成本的 workspace_id 值为 null。

常见用例

环境分离

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

团队或部门隔离

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

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

基于项目的组织

为特定项目或产品创建工作区，以单独跟踪使用量和成本。

最佳实践

1. 1

   规划您的工作区结构

   在创建工作区之前考虑如何组织它们。思考计费、访问控制和使用量跟踪方面的需求。

2. 2

   使用有意义的名称

   清晰地命名工作区以表明其用途（例如"Production - Customer Chatbot"或"Dev - Internal Tools"）。

3. 3

   设置适当的限制

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

4. 4

   定期审核访问权限

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

5. 5

   监控使用量

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

常见问题

另请参阅

• Admin API
• Admin API 参考
• 速率限制
• 使用量和成本 API