接入概览

谁可以接入、有哪些入口，以及工作区、scope、计量与开放范围。

更新于 10月28日

教师可以把脚本、oneai CLI 以及 Claude Code、Codex 这类 agent 接到 OneAI，用来改答卷、解析试卷、读取班级与成绩。各篇示例取自验收时的真实回执。能否接入取决于所在学校，以及 OneAI 是否已开放 API；只有 API 参考标为可调用的操作才已开放。需要对接可先联系我们。

谁可以接入

首批面向教师。客户端代表一位教师执行操作，不获得额外教师、校管或对象所有者身份。学生账号不能给客户端授权。学校可关闭外部客户端入口，之后的调用返回 external.school.disabled。

入口

$ONEAI_ORIGIN 指学校所用的 OneAI 地址。每个入口只接受为它签发的令牌。

入口	地址	令牌 audience
公开 API	`$ONEAI_ORIGIN/api/public/v1`	`public-api`
MCP	`$ONEAI_ORIGIN/mcp`	`mcp`
OAuth	`$ONEAI_ORIGIN/oauth/device_authorization`、`/oauth/authorize`、`/oauth/token`	无

客户端从 /.well-known/oauth-authorization-server 发现授权服务器，从 /.well-known/oauth-protected-resource/mcp 发现 MCP 资源。API 未开放时，外部路由返回 404 external.disabled，OAuth 端点返回 503 temporarily_unavailable。

一个授权对应一个工作区

每次授权固定一位教师与一个工作区，GET /me 会给出是哪一个（姓名与校名已打码）：

{
  "actor": { "id": "2d21d2ba-d28f-4b98-ae9e-f6cd5ef98458", "displayName": "…", "role": "teacher" },
  "workspace": { "id": "2e6e873f-5b19-4d5d-b77d-a091f1c185fd", "name": "…" },
  "authorization": {
    "grantId": "afc20e2e-e29e-4018-8a45-9c03618ef247",
    "clientId": "oneai-pat",
    "scopes": ["profile:read", "classes:read", "grades:read"]
  }
}

X-Workspace-Id 头可以不带；带了但与授权的工作区不同，返回 403 external.workspace.denied。文件、任务和分页游标都属于这个上下文。要访问另一个工作区，需要另一次授权。

scope 与计量

OAuth 元数据列出 21 个 scope。scope 是授权上限，每次调用还要复核教师当前身份、对象关系与学校政策。超出已授 scope 的调用返回 403 external.scope.denied；之后要更多 scope，需要重新授权。写操作、学生实名（students:pii）和原卷（originals:read）都需教师明确同意，CLI 默认不申请。服务端任务使用同一工作区的积分与存储配额；本地 Agent 自己的模型费用另计。

开放范围怎样确认

API 参考由公开契约生成，并标出哪些操作可调用。设计稿和未启用的代码不是可调用能力。首次接入前核对认证方式、工作区和学校政策。

继续阅读

登录与授权