Model

面向添加模型提供方的组织管理员。每项任务需要对应权限。只有平台管理员可以修改 /v1/platform 下的设置。从管理员手册开始。

Bot 需要一个语言模型才能工作。OpenBot 不自带模型。你需要连接一个。OpenBot 为此保存两种记录：

• Model（模型）描述一个语言模型，比如 gpt-5：它的名称、选项和限制。模型不属于某个提供方。
• Model Provider（模型提供方）是一个模型服务和它的访问凭证。提供方会关联它提供的模型。关联可以只为这个提供方修改模型的某些值。

ChatGPT 也使用普通模型提供方。见使用 ChatGPT 登录。账户绑定到提供方。

两者都通过 API 添加。OpenBot 把它们保存在数据库中，所以每个实例使用的都是同一份。

每个模型和每个提供方都归平台或某个组织所有：

所有者	谁添加	谁可以使用
组织	组织，使用自己的密钥	只有这个组织。这就是“自带密钥”。
平台	平台管理员，使用平台的密钥	它的 availability 中列出的组织。参见 Platform。

只有当组织既能使用提供方、也能使用模型时，它才能使用该提供方的这个模型。

每个模型有三种类型之一：

• language 模型会写文本、调用工具。它运行 Turn、评判 Rule，并学习 Bot 记忆。
• decision 模型只从固定的列表中选一个答案。它不写文本。它可以评判 Rule。TypeSafe 的 Jev 就是一个例子。见决策模型。
• live 模型用声音和人实时对话。只有 Live 模式使用它。

当你从代码中运行 OpenBot 时，还可以提供内置模型。参见内置模型。

---

添加模型

POST /v1/organization/models 向你的组织添加一个模型。它需要 ModelProvider 上的 write。

curl -H "Authorization: Bearer $OPENBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "id": "qwen3-32b", "name": "Qwen3 32B", "reasoningEfforts": [], "serviceTiers": [], "contextWindow": 131072 }' \
  https://api.example.com/v1/organization/models

字段	规则
id	必填。1 到 200 个字符。它对所有者来说是唯一的，并且不能修改。提供方把它作为模型名称发送，除非关联设置了 upstream。
name	必填。给人看的名称。
reasoningEfforts	必填。模型接受的 reasoningEffort 值。可以为空。
serviceTiers	必填。模型接受的 serviceTier 值。可以为空。
contextWindow	可选。上下文窗口的大小，单位是 token。
maxOutputTokens	可选。模型在一次回答中最多能写的 token 数。

如果你的组织已经有一个使用这个 id 的模型，OpenBot 会返回 409 和 ModelConflict。

路由	作用
GET /v1/organization/models	列出你组织的模型。共享的模型不在这个列表中。
GET /v1/organization/models/:modelId	读取一个模型。
PATCH /v1/organization/models/:modelId	修改一个模型。请求体需要 expectedVersion。某个限制传 null 即可删除它。
DELETE /v1/organization/models/:modelId	移除一个模型。

读取需要 ModelProvider 上的 read。修改需要 ModelProvider 上的 write。当你的某个提供方关联着一个模型时，你不能移除它。OpenBot 会返回 409 和 ModelInUse。请先移除关联。

添加提供方

POST /v1/organization/model_providers 向你的组织添加一个提供方。它需要 ModelProvider 上的 write。

curl -H "Authorization: Bearer $OPENBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "openai-compat",
    "name": "Local vLLM",
    "endpoint": "https://llm.example.com/v1",
    "apiKey": "sk-...",
    "models": [
      { "model": "qwen3-32b", "modelOwner": "organization", "upstream": "Qwen/Qwen3-32B" }
    ]
  }' \
  https://api.example.com/v1/organization/model_providers

字段	规则
kind	必填。服务使用的 API：openai、anthropic 或 openai-compat。见下表。
name	必填。1 到 120 个字符。
endpoint	对 openai-compat 必填。对其他类型可选。一个 http 或 https 基础 URL，通常以 /v1 结尾。不能带用户名、密码、查询或 # 部分。
apiKey	除 chatgpt 外必填。ChatGPT 使用浏览器登录。
models	必填。0 到 200 个关联。顺序就是模型列表的顺序。

| kind | API | | ————— | ———————————————– | ––––– | | openai | OpenAI Responses API。 | | anthropic | Anthropic Messages API。 | | chatgpt | OpenAI Responses API (OAuth) | language | | openai-compat | OpenAI Chat Completions API，以及仿照它的服务。 |

OpenBot 只连接公网地址。如果模型服务器在你自己的网络中或你的机器上，运维人员必须把它的主机写进 OPENBOT_OUTBOUND_ALLOW。在那之前，对它的调用都会失败。参见出站连接。

每个关联有下面这些字段：

字段	规则
model	必填。模型的 id。一个提供方对每个模型 ID 只能关联一次。
modelOwner	必填。你组织的模型用 organization，共享的模型用 platform。
upstream	可选。服务收到的模型名称，在它不同于模型 id 时使用。
reasoningEfforts	可选。为这个提供方替换模型的 reasoningEfforts。
serviceTiers	可选。为这个提供方替换模型的 serviceTiers。
contextWindow	可选。为这个提供方替换模型的 contextWindow。
maxOutputTokens	可选。为这个提供方替换模型的 maxOutputTokens。

你组织的提供方可以关联你自己的模型，以及平台向你开放的共享模型。对于任何其他模型，OpenBot 会返回 404 和 ModelNotFound。

OpenBot 会返回这个提供方。它的 id 以 prov_ 开头。提供方 ID 在整个平台中是唯一的。模型选择用 provider 指明它。API 密钥永远不会返回。响应中显示的是 apiKey: { set, hint }。参见 Platform。

修改或移除提供方

路由	作用
GET /v1/organization/model_providers	列出提供方。
GET /v1/organization/model_providers/:providerId	读取一个提供方。
PATCH /v1/organization/model_providers/:providerId	修改一个提供方。
DELETE /v1/organization/model_providers/:providerId	移除一个提供方。

读取需要 ModelProvider 上的 read。修改需要 ModelProvider 上的 write。

PATCH 的请求体需要 expectedVersion，也就是你读到的 version。如果有人在你读取之后修改了提供方，OpenBot 会返回 409 和 ModelProviderConflict。不填 apiKey 即可保留当前密钥。发送 models 会替换提供方的所有关联。

curl -X PATCH -H "Authorization: Bearer $OPENBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expectedVersion":0,"apiKey":"sk-new..."}' \
  https://api.example.com/v1/organization/model_providers/prov_4c1e...

修改之后的下一次模型调用会使用新的密钥、端点或关联。OpenBot 对每个模型只构建一次，在它的提供方变化时再重新构建。

当组织设置中的 rulesModel 或 botMemoryModel 指向某个提供方时，你不能移除它。OpenBot 会返回 409 和 ModelProviderInUse。请先修改设置。

---

使用 ChatGPT 登录

chatgpt 模型提供方通过浏览器登录，不使用 API 密钥。提供方归组织或平台所有。所有有权使用它的工作共用所连接的账户。模型关联、权限、价格、预算和平台点数都按普通提供方处理。

通过 POST /v1/organization/model_providers 创建提供方：

{ "kind": "chatgpt", "name": "ChatGPT", "models": [] }

不要发送 apiKey 或 endpoint。保存返回的 prov_* ID。平台提供方使用 /v1/platform/model_providers，并设置 availability。写入需要与 API 密钥提供方相同的权限。

通过提供方 API 发起登录、提交浏览器回调或断开连接。下列路径以 /v1/organization/model_providers/:providerId 开头。平台接口把 organization 换成 platform。

方法与路径	用途
POST /oauth/authorizations	发送 redirectUri 和 expectedVersion，读取 id、url 和 expiresAt。
POST /oauth/authorizations/:authorizationId/complete	发送本机监听程序收到的完整 callbackUrl。
DELETE /oauth	清除令牌并尝试结束远端会话，保留提供方和模型关联。
GET /available_models	通过 items 读取账户可用的上游模型。

本机回调地址是 http://127.0.0.1:<port>/auth/callback。先启动监听，再打开授权地址。登录请求十分钟有效，只能由发起用户完成一次。修改提供方会使旧请求失效。接口支持 API 密钥和同源 session cookie；cookie 写请求需要准确的公共 Origin。服务器加密保存令牌，并按需刷新。

提供方的 oauth 字段返回 connected、loginRequired 和账户资料，不返回令牌。apiKey 字段为 set: false、hint: null。退出返回 revoked: false 时，本地令牌已经清除，但远端退出未获确认。也可以在 ChatGPT 设置中断开应用。

可用模型列表不会修改已存模型。请通过普通 API 添加模型并关联提供方。本地模型 ID 不同时，用列表中的模型 id 作为上游名称。选择模型时使用普通提供方 ID：

{ "_tag": "Config.Selection", "provider": "prov_example", "model": "my-model" }

ChatGPT 支持聊天、规则判断、Bot 记忆和定时工作，支持语言模型与 OpenBot 函数工具，不支持 Live 音频。它使用 Sign in with ChatGPT 和公共 Responses API。账户额度限制仍然有效。登录失效或额度用尽不会让工作自动切换到其他提供方。

类型客户端示例见客户端。

---

选择模型

GET /v1/organization/model_catalog 列出你现在可以使用的模型：也就是你的组织中，你的策略允许对 Model 做 use 的那些模型。每一项都是某个提供方的一个模型，关联中的值已经应用。被两个提供方关联的模型会显示两次。

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

{
  "providers": [
    {
      "id": "prov_4c1e...",
      "owner": "organization",
      "kind": "openai-compat",
      "name": "Local vLLM"
    }
  ],
  "models": [
    {
      "provider": "prov_4c1e...",
      "id": "qwen3-32b",
      "owner": "organization",
      "name": "Qwen3 32B",
      "reasoningEfforts": [],
      "serviceTiers": [],
      "contextWindow": 131072,
      "price": {
        "model": "qwen3-32b",
        "timeZone": "UTC",
        "tiers": [
          {
            "upToInputTokens": null,
            "inputUncached": 400000,
            "inputCacheRead": 100000,
            "inputCacheWrite": 0,
            "output": 1200000,
            "outputReasoning": null
          }
        ],
        "periods": [],
        "effectiveFrom": "2026-10-20T08:00:00.000Z"
      }
    }
  ]
}

price 是这个模型在这个提供方那里的当前价格。没有人设置价格时，它不存在。参见价格。

模型选择同时指明提供方和模型 ID：

{ "_tag": "Config.Selection", "provider": "prov_4c1e...", "model": "qwen3-32b" }

OpenBot 从不替你选模型。没有默认模型。每种用途都要指明自己的模型：

• 新的 Chat 使用它的 Bot 的 model。Bot 没有模型时，给它的第一条消息会失败，返回 400、ChatModelInvalid 和原因 missing。新的 Bot 没有模型，除非你给它一个。所以请在创建时设置它的 model，或之后用 PATCH /v1/bots/:id 设置。
• Rule 的评判使用组织设置中的 rulesModel。它为 null 时，评判不给出答案，由人或 Bot 来决定。
• **Bot 记忆**使用同一份设置中的 botMemoryModel。它为 null 时，Bot 什么都不学。

rulesModel 可以是 language 模型，也可以是 decision 模型。botMemoryModel 必须是 language 模型，因为记忆 Bot 要写文本。否则 OpenBot 返回 400 和 SettingsInvalid。目录会给出每个模型的 type，Chat 只能选择 language 模型。

旧版本的 OpenBot 有 defaultModel 和 helperModel。升级时，OpenBot 把旧的 defaultModel 给每个没有模型的 Bot。rulesModel 和 botMemoryModel 得到旧的辅助模型：helperModel，没有时用 defaultModel。如果两者都是 null，新的值保持为空，你必须设置它们。

例如，要给一个 Bot 设置模型，把它当前的 revision 作为 expected 发送：

curl -X PATCH -H "Authorization: Bearer $OPENBOT_TOKEN" -H 'Content-Type: application/json' \
  -d '{"expected":0,"model":{"_tag":"Config.Selection","provider":"prov_4c1e...","model":"qwen3-32b"}}' \
  https://api.example.com/v1/bots/$BOT_ID

Chat 可以保存自己的选择。把当前的 Chat 修订版本作为 expected 发送：

curl -X PATCH -H "Authorization: Bearer $OPENBOT_TOKEN" -H 'Content-Type: application/json' \
  -d '{"expected":3,"model":{"_tag":"Config.Selection","provider":"prov_4c1e...","model":"qwen3-32b"}}' \
  https://api.example.com/v1/chats/$CHAT_ID

发送 "model": null 可以重新使用 Bot 的模型。GET /v1/chats/:id/models 为一个 Chat 显示同样的模型。所有字段参见 Chats API 参考。

要限制成员可以选择哪些提供方，请给成员一条拒绝规则，针对 Model 上的 use，并用 provider 字段。参见权限。

决策模型

你的组织没有一个专门设置决策模型的地方。每一种用到模型的地方都指明自己的模型。有些地方既可以用决策模型，也可以用语言模型，所以给整个组织固定一个决策模型并不合适。

例如，要通过 TypeSafe 使用 Jev，先添加模型，再添加关联它的提供方：

curl -H "Authorization: Bearer $OPENBOT_TOKEN" -H "Content-Type: application/json" \
  -d '{ "id": "jev-latest", "type": "decision", "name": "Jev", "reasoningEfforts": [], "serviceTiers": [] }' \
  https://api.example.com/v1/organization/models

curl -H "Authorization: Bearer $OPENBOT_TOKEN" -H "Content-Type: application/json" \
  -d '{
    "kind": "typesafe",
    "name": "TypeSafe",
    "endpoint": "https://typesafe.example.com/v1",
    "apiKey": "...",
    "models": [{ "model": "jev-latest", "modelOwner": "organization" }]
  }' \
  https://api.example.com/v1/organization/model_providers

之后，GET /v1/organization/model_catalog 会列出 Jev，并带有 "type": "decision"。

OpenBot 用 Effect 的 TypeSafe 客户端（@effect/ai-typesafe）调用 typesafe 提供方。它把每个请求发到 <endpoint>/systemone，把 API 密钥作为 bearer token，并把 upstream 作为模型名发送。OpenBot 为每个提供方和模型只构建一次客户端，在提供方变化时再重新构建。OpenBot 还不能通过 openai-compat 提供方询问决策模型。你可以在那里关联它，但要询问它，请使用 typesafe 提供方。

Rule 的评判可以使用决策模型。把 rulesModel 设为它即可。见评判模型。

没有模型时运行

没有任何提供方的组织，仍然可以读取它已有的 Chat，并删除它们的历史。它不能和 Bot 说话，因为每个 Turn 都需要模型。见选择模型。

当没有模型能运行一条消息的 Turn 时，发给 Bot 的这条消息会失败，返回状态 503 和错误 ChatExecutionUnavailable：

{ "_tag": "ChatExecutionUnavailable", "chat": "..." }

OpenBot 的通知，例如一个委派的结果，仍然会进入它所在 Chat 的收件箱。见 通知。

---

内置模型

此开发任务请参见 模型后端.

开发用模型

此开发任务请参见 模型后端.