# 工作区

使用工作区组织 API 密钥、管理团队访问和控制成本。

---

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

## 工作区如何工作

每个组织都有一个**默认工作区**，它不能被重命名、归档或删除。当您创建额外的工作区时，您可以为每个工作区分配 API 密钥、成员和资源限制。

主要特征：
- **工作区标识符**使用 `wrkspc_` 前缀（例如，`wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ`）
- 每个组织**最多 100 个工作区**（已归档的工作区不计入）
- **默认工作区**没有 ID，不会出现在列表端点中
- **API 密钥**限定在单个工作区，只能访问该工作区内的资源

### Claude Code 工作区

当您组织的成员首次使用其 Claude Console 账户登录 [Claude Code](https://docs.claude.com/en/docs/claude-code/overview) 时，Anthropic 会自动在组织中创建一个 **Claude Code** 工作区并将该成员添加到其中。每个后续登录 Claude Code 的成员都会以相同方式添加。

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

- Claude Code 在登录时在此工作区中为每个用户生成一个 API 密钥。您无法从控制台手动创建密钥。
- 如果其所有者从工作区或组织中移除，Claude Code 密钥将停止工作，这与标准工作区密钥不同。
- Claude Code 使用量单独进行速率限制，管理员可以在[设置 > 工作区](/settings/workspaces)下限制其在组织限制中的份额。
- 它是唯一支持每月每用户支出限制的工作区。

<Warning>
归档 Claude Code 工作区会为整个组织禁用通过控制台计费的 Claude Code 登录。
</Warning>

## 工作区角色和权限

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

| 角色 | 权限 |
|------|------|
| 工作区用户 | 仅使用工作台 |
| 工作区受限开发者 | 创建和管理 API 密钥，使用 API。无法访问会话跟踪视图或下载文件。 |
| 工作区开发者 | 创建和管理 API 密钥，使用 API |
| 工作区管理员 | 对工作区设置和成员拥有完全控制权 |
| 工作区计费 | 查看工作区计费信息（从组织计费角色继承） |

### 角色继承

- **组织管理员**自动获得所有工作区的工作区管理员访问权限
- **组织计费成员**自动获得所有工作区的工作区计费访问权限
- **组织用户和开发者**必须被显式添加到每个工作区

<Note>
工作区计费角色无法手动分配。它从拥有组织计费角色继承。
</Note>

## 管理工作区

<Note>
只有组织管理员可以创建工作区。组织用户和开发者必须由管理员添加到工作区。
</Note>

### 使用控制台

在 [Claude 控制台](/settings/workspaces)中创建和管理工作区。

#### 创建工作区

<Steps>
  <Step title="打开工作区设置">
    在 Claude 控制台中，转到**设置 > 工作区**。
  </Step>
  <Step title="创建工作区">
    单击**创建工作区**。
  </Step>
  <Step title="配置工作区">
    输入工作区名称并选择颜色以进行视觉识别。
  </Step>
  <Step title="创建工作区">
    单击**创建**以完成。
  </Step>
</Steps>

<Tip>
要在控制台中切换工作区，请使用左上角的**工作区**选择器。
</Tip>

#### 编辑工作区详细信息

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

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

<Note>
默认工作区无法重命名或删除。
</Note>

#### 向工作区添加成员

1. 导航到工作区的**成员**选项卡
2. 单击**添加到工作区**
3. 选择组织成员并为其分配[工作区角色](#工作区角色和权限)
4. 确认添加

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

<Note>
组织管理员和计费成员在持有这些组织角色期间无法从工作区中移除。
</Note>

#### 设置工作区限制

在**限制**选项卡中，您可以配置：

- **速率限制**：为每个模型层级设置每分钟请求数、输入 token 或输出 token 的限制
- **支出通知**：配置当支出达到某些阈值时的警报

#### 归档工作区

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

- 保留历史数据以供报告
- 停用工作区和所有关联的 API 密钥
- 无法撤销

<Warning>
归档工作区会立即撤销该工作区中的所有 API 密钥。此操作无法撤销。如果您归档 [Claude Code 工作区](#claude-code-工作区)，您组织的成员将无法再通过控制台计费登录 Claude Code。
</Warning>

### 使用 Admin API

使用 [Admin API](/docs/en/manage-claude/admin-api) 以编程方式管理工作区。

<Note>
Admin API 端点需要一个 Admin API 密钥（以 `sk-ant-admin...` 开头），它与标准 API 密钥不同。只有具有管理员角色的组织成员才能通过 [Claude 控制台](/settings/admin-keys)配置 Admin API 密钥。
</Note>

```bash cURL
# 创建工作区
curl --request POST "https://api.anthropic.com/v1/organizations/workspaces" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY" \
  --data '{"name": "Production"}'

# 列出工作区
curl "https://api.anthropic.com/v1/organizations/workspaces?limit=10&include_archived=false" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

# 归档工作区
curl --request POST "https://api.anthropic.com/v1/organizations/workspaces/{workspace_id}/archive" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"
```

有关完整的参数详细信息和响应架构，请参阅[工作区 API 参考](/docs/en/api/admin-api/workspaces/get-workspace)。

### 管理工作区成员

添加、更新或移除工作区中的成员：

```bash cURL
# 向工作区添加成员
curl --request POST "https://api.anthropic.com/v1/organizations/workspaces/{workspace_id}/members" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY" \
  --data '{
    "user_id": "user_xxx",
    "workspace_role": "workspace_developer"
  }'

# 更新成员角色
curl --request POST "https://api.anthropic.com/v1/organizations/workspaces/{workspace_id}/members/{user_id}" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY" \
  --data '{"workspace_role": "workspace_admin"}'

# 从工作区移除成员
curl --request DELETE "https://api.anthropic.com/v1/organizations/workspaces/{workspace_id}/members/{user_id}" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"
```

有关完整的参数详细信息，请参阅[工作区成员 API 参考](/docs/en/api/admin-api/workspace_members/get-workspace-member)。

## API 密钥和资源范围

API 密钥限定在特定工作区。当您在工作区中创建 API 密钥时，它只能访问该工作区内的资源。

限定在工作区的资源包括：
- 通过 [Files API](/docs/en/build-with-claude/files) 创建的**文件**
- 通过 [Batch API](/docs/en/build-with-claude/batch-processing) 创建的**消息批次**
- 通过 [Skills API](/docs/en/build-with-claude/skills-guide) 创建的**技能**

某些资源在组织级别管理，无法使用工作区 API 密钥管理：
- **[MCP 隧道](/docs/en/agents-and-tools/mcp-tunnels/overview)**在工作区中创建；控制台 **MCP 隧道**列表和托管智能体服务器选择器仅显示当前工作区中的隧道，而 10 个活动隧道的上限适用于整个组织。隧道管理需要具有隧道管理权限的角色；组织开发者可以查看但不能更改它们。Tunnels API 使用携带 `org:manage_tunnels` 范围的短期 OAuth token 进行身份验证，通过[工作负载身份联合](/docs/en/manage-claude/workload-identity-federation)获得，而不是工作区 API 密钥。
- **工作区**本身和**组织成员**通过 [Admin API](/docs/en/manage-claude/admin-api) 管理，需要 Admin API 密钥。

<Note>
[提示缓存](/docs/en/build-with-claude/prompt-caching)在 Claude API、[Claude Platform on AWS](/docs/en/build-with-claude/claude-platform-on-aws) 和 [Microsoft Foundry](/docs/en/build-with-claude/claude-in-microsoft-foundry)（beta 版）上也按工作区隔离。在 Amazon Bedrock 和 Vertex AI 上，提示缓存按组织隔离。
</Note>

<Tip>
要检索您组织的工作区 ID，请使用[列出工作区](/docs/en/api/admin-api/workspaces/list-workspaces)端点，或在 [Claude 控制台](/settings/workspaces)中找到它们。
</Tip>

## 工作区限制

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

### 设置工作区限制

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

- **支出限制**：限制工作区的每月支出
- **速率限制**：限制每分钟请求数、每分钟输入 token 数或每分钟输出 token 数

<Note>
- 您无法在默认工作区上设置限制
- 如果未设置，工作区限制与组织限制匹配
- 组织范围的限制始终适用，即使工作区限制加起来更多
</Note>

有关速率限制及其工作方式的详细信息，请参阅[速率限制](/docs/en/api/rate-limits)。您还可以使用[速率限制 API](/docs/en/manage-claude/rate-limits-api) 以编程方式读取当前组织和工作区速率限制。

## 使用量和成本跟踪

使用[使用量和成本 API](/docs/en/manage-claude/usage-cost-api) 按工作区跟踪使用量和成本：

```bash cURL
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" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"
```

归属于默认工作区的使用量和成本在 `workspace_id` 中显示为 `null` 值。

## 常见用例

### 环境分离

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

| 工作区 | 用途 |
|--------|------|
| 开发 | 测试和实验，速率限制较低 |
| 预发布 | 生产前测试，具有类似生产的限制 |
| 生产 | 实时流量，具有完整的速率限制和监控 |

### 团队或部门隔离

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

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

### 基于项目的组织

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

## 最佳实践

<Steps>
  <Step title="规划工作区结构">
    在创建工作区之前考虑如何组织它们。考虑计费、访问控制和使用量跟踪需求。
  </Step>
  <Step title="使用有意义的名称">
    清楚地命名工作区以表明其用途（例如，"生产 - 客户聊天机器人"、"开发 - 内部工具"）。
  </Step>
  <Step title="设置适当的限制">
    配置支出和速率限制，以防止意外成本并确保公平的资源分配。
  </Step>
  <Step title="定期审核访问权限">
    定期审查工作区成员资格，确保只有适当的用户具有访问权限。
  </Step>
  <Step title="监控使用量">
    使用[使用量和成本 API](/docs/en/manage-claude/usage-cost-api) 跟踪工作区级别的消耗。
  </Step>
</Steps>

## 常见问题

<section title="什么是默认工作区？">

每个组织都有一个"默认工作区"，它无法被编辑、重命名或移除。此工作区没有 ID，不会出现在工作区列表端点中。归属于默认工作区的使用量在 API 响应中显示为 `workspace_id` 的 `null` 值。

</section>

<section title="什么是 Claude Code 工作区？">

当您组织的成员首次使用其控制台账户登录 Claude Code 时，Anthropic 会自动创建 Claude Code 工作区。它将 Claude Code 的 API 密钥、使用量和速率限制与其他工作负载隔离。有关详细信息，请参阅 [Claude Code 工作区](#claude-code-工作区)。

</section>

<section title="工作区有限制吗？">

是的，每个组织最多可以有 100 个工作区。已归档的工作区不计入此限制。

</section>

<section title="组织角色如何影响工作区访问？">

组织管理员自动获得所有工作区的工作区管理员角色。组织计费成员自动获得工作区计费角色。组织用户和开发者必须手动添加到每个工作区。

</section>

<section title="哪些角色可以在工作区中分配？">

组织用户和开发者可以被分配工作区管理员、工作区开发者、工作区受限开发者或工作区用户角色。工作区计费角色无法手动分配；它从拥有组织 `billing` 角色继承。

</section>

<section title="组织管理员或计费成员的工作区角色可以更改吗？">

只有组织计费成员可以将其工作区角色升级为管理员角色。否则，组织管理员和计费成员在持有这些组织角色期间无法更改其工作区角色或从工作区中移除。必须首先通过更改其组织角色来修改其工作区访问权限。

</section>

<section title="当组织角色更改时，工作区访问会发生什么？">

如果组织管理员或计费成员被降级为用户或开发者，他们将失去对所有工作区的访问权限，除了他们被手动分配角色的工作区。当用户被提升为管理员或计费角色时，他们将自动获得对所有工作区的访问权限。

</section>

<section title="当用户从工作区中移除时，API 密钥会发生什么？">

API 密钥保持其当前状态，因为它们限定在组织和工作区，而不是单个用户。例外是 [Claude Code 工作区](#claude-code-工作区)，其中每个密钥绑定到创建它的成员，并在该成员被移除时停止工作。

</section>

## 另请参阅

- [Admin API](/docs/en/manage-claude/admin-api)
- [Admin API 参考](/docs/en/api/admin)
- [速率限制](/docs/en/api/rate-limits)
- [使用量和成本 API](/docs/en/manage-claude/usage-cost-api)