工作区

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

工作区的工作原理

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

主要特征：

• 工作区标识符使用 wrkspc_ 前缀（例如 wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ）
• 默认情况下，每个组织最多 100 个工作区（已归档的工作区不计入）；如果您需要更多，请联系您的客户团队
• 默认工作区与其他工作区一样拥有 wrkspc_ ID（在 anthropic-workspace-id 响应头中返回，并被 Get Workspace 接受），但只有在您传入 include_default=true 时，它才会出现在 List Workspaces 的结果中；API 密钥、使用量报告和成本报告中其 workspace_id 显示为 null，全工作区 API 密钥也是如此（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 的 Service accounts 页面（platform.claude.com/settings/service-accounts）上添加到工作区：在账户的菜单中或其自身页面上选择 Add to workspace。要查看某个工作区中的账户，请按工作区筛选列表。

管理工作区

使用 Console

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

创建工作区

1. 1

   打开工作区设置

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

2. 2

   打开 Create workspace 页面

   点击 Create workspace，打开 Console 中的 Create workspace 页面（platform.claude.com/settings/workspaces/new）。

3. 3

   配置工作区

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

4. 4

   创建该工作区

   点击 Create workspace 完成创建。

编辑工作区详情

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

1. 从列表中选择工作区。
2. 打开 More actions 菜单（三个点）并选择 Edit details。
3. 更新名称或颜色并保存您的更改。

向工作区添加成员

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

从工作区移除成员

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

设置工作区限制

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

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

归档工作区

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

• 保留历史数据以供报告使用
• 停用工作区并归档为其创建的每个 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}")

有关完整的参数详情和响应结构，请参阅 Workspaces API 参考。

管理工作区成员

向工作区添加成员：

client = anthropic.Anthropic()

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

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

有关完整的参数详情，请参阅 Workspace Members API 参考。

API 密钥和资源限定

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

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

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

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

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

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

要查找您组织的工作区 ID，请调用 List Workspaces 端点（传入 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 报告中以及 Admin API 对象（如 API 密钥）上的 workspace_id 字段（两者对默认工作区都报告 null，API 密钥对全工作区密钥也是如此；API 密钥的 scope 字段可以区分这两者，并且对于绑定到一个工作区的密钥，携带该工作区的真实 ID）
• 使用 Admin API 密钥将其传递给 Get Workspace，以检查它是否为您的默认工作区的 ID：默认工作区会返回 "name": "Default"，尽管除非您传入 include_default=true，否则 List Workspaces 会省略它
• 在 Console 中打开该工作区以查找请求的资源，例如会话、文件、消息批次和技能

工作区限制

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

设置工作区限制

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

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

有关速率限制及其工作原理的详细信息，请参阅速率限制。您还可以使用速率限制 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"

归属于默认工作区的使用情况和成本的 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