快速开始

本页描述网页型开放智能体使用 OAuth 2.0 获取模型权益的最短路径。OAuth Token、Client Secret 和授权码都必须只由可信服务端处理。

1. 在开放平台登记智能体

准备以下信息并由平台运营人员完成登记：

• 智能体名称与公开说明；
• 精确的 HTTPS 入口或回调地址；
• 实际需要的 OAuth Scope；
• 网页允许来源或 MCP 服务地址；
• 安全审查和发布状态。

平台只在创建或轮换时展示一次 Client Secret。服务端应立即写入密钥管理系统，禁止写入 Git、浏览器构建变量、日志或 AI 上下文。

2. 请求正确的授权上下文

Personal 模型访问至少申请：

profile model

如果网页还需要展示余额、读取归因用量或主动扣费，再按需增加：

balance usage charge

Team 访问必须显式提供目标 team_id，并按操作申请 team_read 或 team_manage。不要把 Personal Token 静默改绑到 Team。

3. 用授权码交换 Token

POST /oauth/token
Content-Type: application/x-www-form-urlencoded
Accept: application/json

grant_type=authorization_code&client_id=<client-id>&client_secret=<client-secret>&code=<single-use-code>&redirect_uri=<registered-redirect-uri>

新授权码交换得到的 Access Token 默认有效 7 天，不签发新的 Refresh Token。Token 到期或授权失效后，应引导用户重新授权或从小雅 App 重新打开智能体。

4. 查询可用模型

Personal：

GET /api/v1/open/models
Authorization: Bearer <access-token>

Team：

GET /api/v1/open/teams/<team-id>/models
Authorization: Bearer <team-bound-access-token>

只使用响应返回的 modelCode 和 parameterSpec。不要硬编码供应商模型名、Base URL 或内部路由。

5. 调用模型

Personal Token 可以调用兼容 Chat Completions 的模型网关：

POST /api/proxy/v1/chat/completions
Authorization: Bearer <access-token>
Content-Type: application/json

{
  "model": "<modelCode>",
  "messages": [{ "role": "user", "content": "你好" }],
  "stream": true
}

Team Token 需要完整工作流 Header，并且当前只能使用 "stream": false。详见 Team 上下文。

6. 处理统一响应和错误

开放 API 成功响应：

{ "success": true, "data": {}, "request_id": "trace-id" }

开放 API 失败响应：

{
  "success": false,
  "code": "STABLE_ERROR_CODE",
  "message": "Safe message",
  "request_id": "trace-id"
}

日志只记录稳定错误码和 request_id。不要记录 Authorization、Token、Code、Client Secret、完整用户资料或模型输入。