Team 上下文

查询账户实际权益

个人调用 GET /api/v1/open/account/entitlements，需要 account Scope；团队调用 GET /api/v1/open/teams/{team_id}/entitlements，需要 team_read 或 team_manage。Team Token 不能读取个人或其他团队权益。两者均在标准 data 中返回 accountType、accountId、entitlements 和 sources；个人 accountId 是当前应用隔离的用户 subject。

entitlements.storage.maxFileBytes 是单文件权益上限，totalBytes 是总存储权益额度，均以字节表示；Team 另含 memberLimit（含所有者）及 planFeatures，个人含 byok。sources 包含有效来源、具体权益、startsAt/endsAt，时间为 UTC，空结束时间表示长期有效。会员只是限时权益来源，客户端不能仅凭会员名称判断权限；多个来源按更高额度合并，购买人数累加。服务端仍检查角色、对象归属、余额和具体功能门禁。

上传超出权益返回 ATTACHMENT_FILE_LIMIT_REACHED 或 ATTACHMENT_STORAGE_LIMIT_REACHED（HTTP 413），应提示调整权益或释放空间，不要重复提交。存储服务及专用媒体接口仍可能有技术上限；会员到期不会删除已有文件。团队人数增购在团队门户采购页完成，按本期剩余时间计价，与本期会员同日到期。

团队须先激活席位套餐再购买积分。会员读取结果中的 canPurchaseCredits 表示能否订购积分包，不能用积分余额或 accessActive 替代；没有有效套餐时服务端返回 TEAM_CREDIT_PACK_PLAN_REQUIRED（HTTP 402），管理员代下单也执行此限制。套餐目录 seats 提供 includedMembers、allowPurchase 和 monthlyPriceMinor，人数包含所有者。积分包仅充值，accessDays 固定为 0，不激活团队、不延长套餐；已有积分保留原本的有效期，套餐到期后需续购套餐才能恢复团队模型调用。

Team OAuth 不是 Personal OAuth 的透明升级。一个 Team Token 会精确绑定用户、开放智能体、Team、成员、授权记录和上下文版本；任何跨 Team 或 Personal/Team 串用都会失败关闭。

获取 Team Token

推荐始终在授权请求中显式传递 team_id。请求 team_read 或 team_manage 但不传 team_id 时，平台可以进入 Team 选择页，但第三方客户端仍应对该浏览器流程单独验收。

普通成员不能获得 team_manage；只有 Owner/Admin 可以授权管理 Scope。成员被禁用、移出 Team、角色降级或 Team 停用后，旧 Token 和历史授权不能继续使用。

Team-bound Open Agent 调用模型网关必须同时携带：

http

X-Xiaoya-Team-Id: <team-id>
X-Xiaoya-Workflow-Version-Id: <workflow-version-id>
X-Xiaoya-Run-Id: <run-id>
X-Xiaoya-Node-Id: <node-id>
X-Xiaoya-Attempt: <1..6>

这组字段不是展示元数据，而是 Team 预占、结算、退款和幂等边界。必须由可信工作流服务端产生，不能让浏览器或 AI 自由填写。

当前流式限制

Team 模型调用当前必须使用：

json

{ "stream": false }

使用 stream=true 会返回：

text

TEAM_USAGE_STREAMING_UNSUPPORTED

缺少完整工作流上下文会返回：

text

TEAM_USAGE_CONTEXT_INCOMPLETE

因此，依赖 SSE 的对话型智能体目前不能直接把 Team Token 当作普通 OpenAI API Key 使用。可以先使用 Personal Token 流式调用，或把 Team 场景设计为可恢复的非流式工作流节点。

余额、目录和用量

Team 余额：GET /api/v1/open/teams/{team_id}/balance；
Team 模型：GET /api/v1/open/teams/{team_id}/models；
Team 概览：Team 管理接口提供月调用数和积分消耗；
Personal /api/v1/open/usage 不接受 Team-bound Token。

当前没有与 Personal /open/usage 完全对等的 Team 明细接口。不要把 Team Overview 伪装为相同粒度的用量明细。

Team 上下文与余额调用示例：

bash

curl 'https://claw.zhenhuiai.com/api/v1/open/teams/team_01/context' \
  --header 'Authorization: Bearer <team-access-token>'

curl 'https://claw.zhenhuiai.com/api/v1/open/teams/team_01/balance' \
  --header 'Authorization: Bearer <team-access-token>'

json

{
  "success": true,
  "data": {
    "teamId": "team_01",
    "teamContextVersion": 7,
    "memberId": "member_01",
    "role": "member",
    "memberStatus": "active"
  },
  "request_id": "req_team_context"
}

json

{
  "success": true,
  "data": {
    "teamId": "team_01",
    "total": 12500,
    "memberQuota": 1000,
    "memberRemaining": 860
  },
  "request_id": "req_team_balance"
}

Team 网页业务扣费使用 POST /api/v1/open/teams/{team_id}/charge，退款使用 /refund。两者都必须使用 Team Token，积分和幂等键由可信后端生成，并与 Personal 订单键空间隔离：

json

{
  "points": 20,
  "idempotencyKey": "team_order_20260830_0001"
}

json

{
  "points": 20,
  "chargeIdempotencyKey": "team_order_20260830_0001",
  "idempotencyKey": "team_refund_20260830_0001"
}

Team 模型网关完整示例：

bash

curl 'https://claw.zhenhuiai.com/api/proxy/v1/chat/completions' \
  --header 'Authorization: Bearer <team-access-token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Xiaoya-Team-Id: team_01' \
  --header 'X-Xiaoya-Workflow-Version-Id: workflow_version_01' \
  --header 'X-Xiaoya-Run-Id: run_01' \
  --header 'X-Xiaoya-Node-Id: summarize' \
  --header 'X-Xiaoya-Attempt: 1' \
  --data '{
    "model":"othan-2.0",
    "messages":[{"role":"user","content":"总结企业知识库更新"}],
    "stream":false
  }'

常见错误

错误码	含义
`TEAM_CONTEXT_MISMATCH`	Personal/Team 或不同 Team 上下文被串用
`TEAM_OAUTH_AUTHORIZATION_REQUIRED`	Personal Token 试图访问需要 Team 授权的资源
`TEAM_USAGE_CONTEXT_INCOMPLETE`	缺少工作流执行 Header
`TEAM_USAGE_STREAMING_UNSUPPORTED`	Team 请求使用了流式输出
`OPEN_AGENT_SCOPE_REQUIRED`	Token 缺少目标接口需要的 Scope

所有 Team 管理、成员、角色、部门、职位、组织角色、共享资产、执行授权、运行时资产与沙箱接口均收录在完整 API 参考，并按真实路由标注 Scope、参数、请求体和响应 Schema。

Team 上下文 ​

查询账户实际权益 ​

获取 Team Token ​

Team 模型调用 Header ​

当前流式限制 ​

余额、目录和用量 ​

常见错误 ​

Team 上下文

查询账户实际权益

获取 Team Token

Team 模型调用 Header

当前流式限制

余额、目录和用量

常见错误