Platform

面向平台运维人员。这些任务会影响整个部署。请按任务要求准备服务器访问权限或平台管理权限。从管理员手册开始。

Platform（平台）就是整个 OpenBot 部署。一个平台有许多组织。平台管理员负责运行平台。本页介绍如何设置平台，以及如何用 /v1/platform 管理它。

---

平台管理员

平台管理员管理平台。平台管理员不是每个组织的成员。除非他也是某个组织的成员，否则他不能读取这个组织的 Chat、Bot 或成员。他只能通过 /v1/platform 管理平台。

平台管理员是一个电子邮件地址。当有人第一次用这个邮箱登录、并且提供方已验证该邮箱时，这个条目会关联到那个账号。

路由	作用
GET /v1/platform/admins	列出平台管理员。
POST /v1/platform/admins	添加一个平台管理员。请求体是 { email }。
DELETE /v1/platform/admins/:email	移除一个平台管理员。

curl -b cookies.txt \
  -H "Origin: https://api.example.com" \
  -H "Content-Type: application/json" \
  -d '{"email":"bob@example.com"}' \
  https://api.example.com/v1/platform/admins

{
  "email": "bob@example.com",
  "userId": null,
  "addedAt": "2026-10-21T09:00:00.000Z"
}

在 Bob 第一次登录之前，userId 为 null。平台必须至少保留一个管理员。移除最后一个管理员会返回 409 和 LastPlatformAdmin。

---

设置

新数据库中没有平台设置。在你运行设置程序之前，除 /health 之外的每个路由都会返回 503 和 SetupRequired。

设置程序用 OPENBOT_DATABASE_URL 和 OPENBOT_SECRET_KEYS 连接数据库。它会写入第一份平台设置和第一批平台管理员。在镜像中，它是 /app/dist/app/Setup.mjs。从源代码运行时，使用 pnpm --filter @openbot-build/openbot setup。这个包还提供命令 openbot-setup。

docker run --rm --env-file openbot.env openbot:$OPENBOT_RELEASE \
  /app/dist/app/Setup.mjs \
  --public-origin=https://api.example.com \
  --oidc-issuer=https://id.example.com \
  --oidc-client-id=openbot \
  --admin-email=alice@example.com

参数	必需	作用
--public-origin	是	OpenBot 的公开 HTTPS 源，比如 https://api.example.com。不带路径，结尾不带斜杠。
--oidc-issuer	与 ID 一起	平台 OpenID Connect 提供方的 HTTPS 地址，结尾不带斜杠。
--oidc-client-id	与 issuer 一起	在该提供方那里的客户端 ID。
--oidc-client-secret	否	客户端密钥。对于使用 PKCE 的公开客户端，不填。
--admin-email	至少一个	拥有这个已验证邮箱的人登录后会成为平台管理员。要添加更多人，就重复这个参数。
--s3-endpoint	和 bucket 一起	文件的对象存储地址，例如 https://s3.us-east-1.amazonaws.com。
--s3-public-endpoint	否	客户端直接上传文件时用的地址，当它不是 --s3-endpoint 时设置。
--s3-region	否	存储的区域。默认是 us-east-1。
--s3-bucket	和地址一起	存放文件的 bucket。
--s3-access-key-id	和地址一起	存储的访问密钥 ID。
--s3-secret-access-key	和地址一起	存储的密钥。
--s3-path-style	否	把 bucket 放在路径里。MinIO 和 RustFS 需要它。
--force	否	即使设置已存在也写入。只在恢复时使用，也就是没有任何平台管理员能登录的时候。

--oidc-issuer 和 --oidc-client-id 要么一起设置，要么都不设置。当大家只通过各组织的 SSO 连接登录时，两者都不设置。

命令行可能会出现在进程列表中。所以，你可以改用环境变量 OPENBOT_SETUP_OIDC_CLIENT_SECRET 提供客户端密钥，而不是 --oidc-client-secret。这是更好的做法。

四个存储参数 --s3-endpoint、--s3-bucket、--s3-access-key-id 和 --s3-secret-access-key 要一起设置，或者都不设置。你也可以用 OPENBOT_SETUP_S3_SECRET_ACCESS_KEY 提供密钥。不设置时，平台没有存储，直到管理员在平台设置中设置 files。

设置程序还会生成一个随机的登录密钥。Better Auth 用它来签名登录 cookie。OpenBot 加密保存它，你永远看不到它。

再次运行设置

• 使用同样的源和提供方时，设置程序什么也不改。它只会添加管理员邮箱。
• 使用其他值时，设置程序会失败。它会告诉你改用 PATCH /v1/platform/settings。
• 使用 --force 时，设置程序会写入新的值。它会保留当前的登录密钥，所以不会因此让任何人退出登录。

---

平台设置

GET /v1/platform/settings 读取设置。PATCH /v1/platform/settings 修改设置。

curl -H "Authorization: Bearer $OPENBOT_TOKEN" \
  https://api.example.com/v1/platform/settings

{
  "version": 3,
  "publicOrigin": "https://api.example.com",
  "identityProvider": {
    "issuer": "https://id.example.com",
    "clientId": "openbot",
    "clientSecret": {
      "set": true,
      "hint": "…k9Qz"
    }
  },
  "organizationCreation": "anyone",
  "ceiling": "{\"_tag\":\"Rules\",\"algorithm\":\"denyOverrides\",\"rules\":[]}",
  "appRestrictions": [],
  "codeMode": {
    "enabled": false,
    "timeoutMs": 30000,
    "memoryMb": 64,
    "outputBytes": 65536
  },
  "rateLimit": {
    "requestsPerMinute": null
  },
  "tokenRate": {
    "organization": null,
    "member": null,
    "bot": null,
    "token": null
  },
  "files": {
    "storage": null,
    "uploads": {
      "server": true,
      "direct": true
    },
    "maxBytes": 20971520,
    "quotaBytes": null,
    "mediaTypes": [
      "image/png",
      "image/jpeg",
      "image/gif",
      "image/webp",
      "application/pdf",
      "text/plain"
    ],
    "unusedMs": 86400000
  },
  "updatedAt": "2026-10-21T09:00:00.000Z"
}

字段	是什么
version	每次修改加一。
publicOrigin	OpenBot 的公开 HTTPS 源。
identityProvider	平台的 OpenID Connect 提供方；当大家只通过 SSO 连接登录时为 null。
organizationCreation	谁可以创建组织：anyone 或 platform_admins。参见组织创建。
ceiling	一个带拒绝规则、对每个组织生效的策略。参见策略上限。
appRestrictions	App Index 隐藏的 App。参见 App Index。
codeMode	Bot 能否使用 Code Mode，以及它的限制。参见 Code Mode。
rateLimit	每个调用方在一分钟内最多可以发送多少个 API 请求。参见速率限制。
tokenRate	每个范围最高的 token 速率。组织只能设置更低的速率。参见 token 速率。
files	文件的对象存储和限制。
updatedAt	设置最后一次修改的时间。

机密永远不会返回

机密可以写入，但永远不会读出。响应中显示的是 { set, hint }：

• 当保存了机密时，set 为 true。
• hint 是 … 加上最后 4 个字符，方便你区分不同的机密。对于短于 12 个字符的机密，它为 null。

修改设置

PATCH 的请求体需要 expectedVersion，也就是你读到的 version。只加入你想修改的字段。

curl -X PATCH -H "Authorization: Bearer $OPENBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expectedVersion":3,"organizationCreation":"platform_admins"}' \
  https://api.example.com/v1/platform/settings

如果有人在你读取之后修改了设置，OpenBot 会返回 409 和 SettingsConflict，以及当前的 version。请重新读取设置，然后再试一次。

PATCH 中的 identityProvider 是这样工作的：

值	结果
null	移除平台提供方。
{ issuer, clientId }	设置提供方，并保留当前的密钥。
{ issuer, clientId, clientSecret: "…" }	设置提供方和一个新的密钥。
{ issuer, clientId, clientSecret: null }	把提供方设置为公开的 PKCE 客户端。

每个实例都会立刻使用修改后的值。参见配置。

警告

新的 publicOrigin 会让所有人退出登录。它还会把登录重定向 URI 改为 <publicOrigin>/auth/callback/oidc。请先在你的提供方那里添加新的重定向 URI，然后再修改源。

---

策略上限

ceiling 是一个在每个组织中都生效的策略。它只能有拒绝规则。来自上限的拒绝总是胜出，所以任何角色、任何令牌都不能做它拒绝的事。条件中可以使用调用者的 organizationId。参见权限。上限对平台 API 不生效，所以它永远不会把平台管理员锁在外面。

下面这个上限禁止每个组织添加自己的模型提供方：

{
  "expectedVersion": 4,
  "ceiling": "{\"_tag\":\"Rules\",\"algorithm\":\"denyOverrides\",\"rules\":[{\"_tag\":\"Deny\",\"actions\":[\"write\"],\"resources\":[\"ModelProvider\"],\"reason\":\"The platform gives the model providers.\"}]}"
}

带有允许规则的上限会返回 400。请求中的上限最多可以有 100 条规则。

---

组织创建

organizationCreation 决定谁可以调用 POST /v1/organizations。账号登录时，OpenBot 不会为它创建组织。

值	结果
anyone	默认值。任何登录的人都可以创建组织。
platform_admins	只有平台管理员可以创建组织。其他人通过邀请、已验证的域名或 SSO 加入。

账号加入组织的所有方式，参见组织。

---

组织

GET /v1/platform/organizations 分页列出平台的所有组织。使用 limit（1 到 100），以及值为上一页 next 的 after。

PATCH /v1/platform/organizations/:organizationId 修改组织的 status：active 或 suspended。

curl -X PATCH -H "Authorization: Bearer $OPENBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status":"suspended"}' \
  https://api.example.com/v1/platform/organizations/org_8f3a

任何人都不能使用被暂停的组织。它的令牌会立刻失效。把 status 设为 active 即可撤销暂停。

GET /v1/platform/organizations/:organizationId/credits 读取一个组织的额度。对同一路由使用 PATCH 可以打开或关闭额度，POST .../credits/grants 给出额度。参见额度。

---

共享的模型提供方

平台可以为模型提供方付费，并把它们共享给各个组织。它也可以共享模型。组织也可以使用自己的密钥。参见 Model。

路由	作用
GET /v1/platform/models	列出共享的模型。
POST /v1/platform/models	添加一个共享的模型。
GET /v1/platform/models/:modelId	读取一个共享的模型。
PATCH /v1/platform/models/:modelId	修改一个共享的模型。
DELETE /v1/platform/models/:modelId	移除一个共享的模型。
GET /v1/platform/model_providers	列出共享的提供方。
POST /v1/platform/model_providers	添加一个共享的提供方。
GET /v1/platform/model_providers/:providerId	读取一个共享的提供方。
PATCH /v1/platform/model_providers/:providerId	修改一个共享的提供方。
DELETE /v1/platform/model_providers/:providerId	移除一个共享的提供方。
GET /v1/platform/model_providers/:providerId/prices	列出一个共享的提供方的价格。参见价格。
PUT /v1/platform/model_providers/:providerId/prices	为一个共享的提供方中的一个模型设置新价格。

请求体和组织的模型与提供方相同，只是多了 availability。先添加模型，再添加一个关联它的提供方：

curl -H "Authorization: Bearer $OPENBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "id": "gpt-4.1", "name": "GPT-4.1", "reasoningEfforts": [], "serviceTiers": [], "availability": { "_tag": "All" } }' \
  https://api.example.com/v1/platform/models

curl -H "Authorization: Bearer $OPENBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "openai",
    "name": "OpenAI",
    "apiKey": "sk-...",
    "models": [{ "model": "gpt-4.1", "modelOwner": "platform" }],
    "availability": { "_tag": "All" }
  }' \
  https://api.example.com/v1/platform/model_providers

availability	谁可以使用这个模型或提供方
{ "_tag": "All" }	每个组织。
{ "_tag": "None" }	没有任何组织。
{ "_tag": "Selected", "organizations": ["org_…"] }	只有列出的组织。

只有当两者的 availability 都允许时，组织才能看到共享提供方的共享模型。组织也可以把一个它能使用的共享模型关联到自己的提供方。这时它用自己的密钥使用这个模型。

共享提供方只能关联共享模型。当某个共享提供方关联着一个共享模型时，你不能移除这个模型：OpenBot 会返回 409 和 ModelInUse。当你移除一个共享模型时，OpenBot 也会移除各组织的提供方与它之间的关联。

---

调用平台 API

/v1/platform 接受两种调用者：

• 平台管理员的 session cookie。
• 平台管理员的用户令牌。令牌自身的策略必须允许 Platform 上的 read（用于 GET）或 write（用于其他所有方法）。

组织中的任何角色都不会授予 Platform 上的操作。没有指定 policy 创建的令牌永远得不到它们。所以，用于平台的令牌必须在创建时写明它们：

curl -b cookies.txt \
  -H "Origin: https://api.example.com" \
  -H "Content-Type: application/json" \
  -d '{"name":"Platform admin","expiresInDays":30,"policy":"{\"_tag\":\"Rules\",\"algorithm\":\"denyOverrides\",\"rules\":[{\"_tag\":\"Allow\",\"actions\":[\"read\",\"write\"],\"resources\":[\"Platform\"]}]}"}' \
  https://api.example.com/v1/user/tokens

只有在它的账号仍是平台管理员时，令牌才有效。其他调用者会得到 403 和 Forbidden。

OpenBot 把每次平台修改写入审计日志，组织 ID 为 platform。API 目前还不能读取这些条目。

在 Platform 参考中查看完整的结构。

---

错误

状态	错误	何时
400	SettingsInvalid	修改中的某个值无效。
403	Forbidden	调用者不是平台管理员，或者令牌不允许。
404	OrganizationNotFound	没有这个 ID 的组织。
404	PlatformAdminNotFound	没有使用这个邮箱的平台管理员。
409	SettingsConflict	有人在你读取之后修改了设置。
409	LastPlatformAdmin	这次修改会让平台没有管理员。
503	SetupRequired	还没有人运行过设置程序。
503	PlatformUnavailable	OpenBot 无法访问它的数据库。