组织

本页说明多人如何共用 OpenBot。组织（Organization）是一群人，他们共享 Agents、模型和设置。 一个平台有很多组织。一个账户可以是其中多个组织的成员。一个人单独使用 OpenBot 时，他有一个只有一名成员的组织。

当前组织的路由都在 /v1/organization 下。它们接受用户令牌或 session cookie。使用 cookie 时，如果你属于多个组织，请发送 OpenBot-Organization 请求头。见 身份验证。

---

谁可以加入

每次账户登录时，OpenBot 都会检查它属于哪里。在每个带 session cookie 的请求上，它也会检查。

方式	得到的角色	需要的条件
已验证的域名	组织的 defaultRoles	组织验证了邮箱的域名，joinByDomain 为 true，并且提供方验证了邮箱。
SSO 连接	组织的 defaultRoles	账户通过该组织的 SSO 连接登录。
个人组织	在一个名为 “Personal” 的新组织中得到 super_administrator	账户没有任何组织，并且平台设置中的 organizationCreation 为 anyone。
新组织	super_administrator	账户调用 POST /v1/organizations。见 创建组织。

没有任何组织的账户，访问组织路由时会得到 403 和 MembershipRequired。 验证域名见 SSO 和域名，organizationCreation 见 Platform。

---

你的组织

GET /v1/organizations 列出你作为成员所在的组织。用户令牌只能看到它自己的组织。

curl -b cookies.txt https://api.example.com/v1/organizations

{
  "items": [
    {
      "id": "org_8f3a",
      "name": "Example",
      "status": "active",
      "createdAt": "2026-10-21T09:00:00.000Z"
    }
  ]
}

status 是 active 或 suspended。平台管理员可以暂停一个组织。暂停后，没有人能使用它，它的令牌也会失效。见 Platform。

创建组织

POST /v1/organizations 创建一个组织。你会成为它的 Super Administrator（超级管理员）。

curl -b cookies.txt \
  -H "Origin: https://api.example.com" \
  -H "Content-Type: application/json" \
  -d '{"name":"Research"}' \
  https://api.example.com/v1/organizations

当平台设置中的 organizationCreation 为 platform_admins 时，只有平台管理员能这样做。其他调用者会得到 403 和 OrganizationCreationDisabled。

---

读取和修改组织

GET /v1/organization 读取当前组织。它返回和上面相同的对象。 PATCH /v1/organization 修改组织的 name。它需要 organization.write。

curl -X PATCH -H "Authorization: Bearer $OPENBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Example Inc."}' \
  https://api.example.com/v1/organization

---

设置

每个组织都有自己的设置。设置保存在数据库中，所以每个 OpenBot 实例使用相同的值。 GET /v1/organization/settings 读取设置。它需要 organization.read。

{
  "version": 2,
  "rulesModel": {
    "_tag": "Config.Selection",
    "provider": "prov_4c1e...",
    "model": "gpt-4.1-mini"
  },
  "agentMemoryModel": null,
  "decisionModel": null,
  "memory": { "use": true, "generate": true },
  "agentMemory": true,
  "requestTimeoutMs": 86400000,
  "planApproval": {
    "approver": "chain",
    "timeoutMs": 86400000,
    "onTimeout": "stay"
  },
  "appReadRules": [],
  "defaultRoles": ["member"],
  "joinByDomain": true,
  "updatedAt": "2026-10-21T09:00:00.000Z"
}

字段	默认值	作用
rulesModel	null	用来判断 Rules 的模型。null 表示没有模型判断它们。见 Models。
agentMemoryModel	null	用来学习 Agent memory 的模型。null 表示 Agent 什么都不学。
decisionModel	null	决策模型，例如 Jev。它必须是 decision 模型。null 表示没有。见 Models。
memory	都开启	新 Session 的记忆开关 use 和 generate。见 Memory。
agentMemory	true	每个 Turn 结束后学习 Agent memory。
requestTimeoutMs	24 小时	一个 request 等待回答的时间，超时后 OpenBot 会拒绝它。范围是 1 秒到 7 天。
planApproval	问上一级决策者，24 小时后仍是计划	当成员、Agent 和 Session 都没有设置时，计划如何被批准。见 计划模式。
appReadRules	[]	只读取数据的 App 工具：{ cardUrl, tool }。见 Requests。
defaultRoles	["member"]	新成员的角色。
joinByDomain	true	拥有组织已验证域名下已验证邮箱的人，在登录时加入组织。

PATCH /v1/organization/settings 修改设置。它需要 organization.write。请求体需要 expectedVersion，也就是你读到的 version。只添加你想修改的字段。

curl -X PATCH -H "Authorization: Bearer $OPENBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expectedVersion":2,"requestTimeoutMs":3600000,"joinByDomain":false}' \
  https://api.example.com/v1/organization/settings

• 如果在你读取之后有人修改了设置，OpenBot 返回 409 和 SettingsConflict，以及当前的 version。请重新读取，然后再试一次。
• 不存在的角色会返回 400 和 SettingsInvalid。
• 只有 Super Administrator 能把 super_administrator 放进 defaultRoles。

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

---

成员

GET /v1/organization/members 分页列出成员。它需要 members.read。使用 limit（1 到 100，默认 50），并用上一页的 next 值作为 after。

{
  "items": [
    {
      "userId": "u_123",
      "email": "ada@example.com",
      "name": "Ada",
      "status": "active",
      "roles": ["super_administrator"],
      "policies": [],
      "joinedAt": "2026-10-21T09:00:00.000Z"
    }
  ],
  "next": null
}

GET /v1/organization/members/:userId 读取一个成员。

修改成员

PATCH /v1/organization/members/:userId 修改 status、roles 或 policies。它需要 members.write。

• status 是 active 或 suspended。被暂停的成员不能使用这个组织，他们在这个组织的令牌会立即失效。
• roles 是角色 ID 的列表：包括内置角色和自定义角色。见 权限。
• policies 是成员的额外策略，在角色之外另外生效。

curl -X PATCH -b cookies.txt \
  -H "Origin: https://api.example.com" \
  -H "Content-Type: application/json" \
  -d '{"roles":["administrator"]}' \
  https://api.example.com/v1/organization/members/u_456

移除成员

DELETE /v1/organization/members/:userId 移除成员，并撤销他们的令牌。它需要 members.write。 如果他们的邮箱域名仍然是已验证的，并且 joinByDomain 是开启的，或者他们通过 SSO 连接登录，那么他们下次登录时会再次加入。要让他们无法进入，请暂停他们。

Super Administrator 的规则

• 只有 Super Administrator 能修改或移除 Super Administrator，或者把这个角色给别人。
• 只有 Super Administrator 能给成员额外的 allow 策略，或者把 super_administrator 放进默认角色。其他管理员只能添加 deny 策略。所以，没有人能给出比自己更多的权限。
• 组织至少保留一个活跃的 Super Administrator。破坏这一点的修改会返回 409 和 LastSuperAdministrator。

---

审计日志

审计日志记录重要的修改。任何操作都不能修改或删除日志条目。 GET /v1/organization/audit_logs 列出条目，最新的排在前面。它需要 audit_logs.read。

查询参数	作用
limit	1 到 100。默认值是 50。
after	上一页的 next 值。
action	只返回这个动作的条目。
actor	只返回这个用户 ID 的成员产生的条目。

{
  "items": [
    {
      "id": "42",
      "createdAt": "2026-10-21T09:05:00.000Z",
      "action": "member.updated",
      "actor": {
        "kind": "member",
        "userId": "u_123",
        "organizationId": "org_8f3a"
      },
      "resource": "openbot.org.org_8f3a.user.u_456",
      "details": {
        "before": { "status": "active", "roles": ["member"], "policies": 0 },
        "after": {
          "status": "active",
          "roles": ["administrator"],
          "policies": 0
        }
      }
    }
  ],
  "next": "42"
}

动作	何时出现
member.joined	一个账户加入组织。
member.updated	一个成员得到新的状态、角色或策略。
member.removed	一个成员被移除。
organization.created	有人创建了一个组织。
organization.updated	组织得到了新名称。
settings.updated	组织设置发生变化。
role.created	一个成员创建了自定义角色。
role.updated	一个成员修改了自定义角色。
role.deleted	一个成员删除了自定义角色。
model.created	一个成员添加了模型。
model.updated	一个成员修改了模型。
model.deleted	一个成员移除了模型。
model_provider.created	一个成员添加了模型提供方。
model_provider.updated	一个成员修改了模型提供方。
model_provider.deleted	一个成员移除了模型提供方。
domain.added	一个成员添加了邮箱域名。
domain.verified	一个邮箱域名通过了验证。
domain.removed	一个成员移除了邮箱域名。
sso_connection.created	一个成员添加了 SSO 连接。
sso_connection.updated	一个成员修改了 SSO 连接。
sso_connection.deleted	一个成员移除了 SSO 连接。
token.created	一个成员创建了用户令牌。
token.revoked	一个成员撤销了用户令牌。
agent.created	一个成员创建了 Agent。
agent.updated	一个成员修改了 Agent。
agent.promoted	一个成员提升了一个 Session Agent。
agent.memory.updated	一个成员修改了 Agent memory。
delegation.started	一个 Agent 把工作交给另一个 Agent。
delegation.completed	委派的工作结束。
capability.decided	一个人回答了一个 request。
request.resolved	一个 request 关闭。details.chain 列出相关的 Agents。
grant.created	一个成员创建了 Grant（授权）。
grant.revoked	一个成员撤销了 Grant。
rule.created	一个成员添加了 Rule。
rule.updated	一个成员修改了 Rule。

---

错误

状态码	错误	何时出现
400	PolicyInvalid	某个策略指定了组织之外的资源。
403	PermissionDenied	调用者没有该权限。见 权限。
400	OrganizationRequired	使用 cookie 的请求没有 OpenBot-Organization，而你属于多个组织。
400	SettingsInvalid	设置中的某个值无效，例如角色不存在。
403	MembershipRequired	你不是这个组织的活跃成员。
403	OrganizationCreationDisabled	在这个平台上，只有平台管理员能创建组织。
404	MemberNotFound	没有成员使用这个用户 ID。
409	SettingsConflict	在你读取之后，有人修改了设置。
409	LastSuperAdministrator	这个修改会导致没有活跃的 Super Administrator。
503	OrganizationStorageUnavailable	OpenBot 无法连接到它的数据库。