跳到主要内容

成员 (Members)

成员 (Member) 是你的用户在 OpenHex 工作区里的身份——每个成员有自己的计费账户、积分余额和会话令牌。 你用自己系统里的用户 ID（sp_user_ref）开通成员，之后所有操作都围绕这个引用展开，不需要在你的数据库里保存 OpenHex 的 id。

本页示例都基于一个绑定了 slug 的工作区句柄：

import { OpenhexClient } from '@openhex-ai/agent-sdk';

const ws = new OpenhexClient({ apiKey: process.env.OPENHEX_WORKSPACE_KEY! })
  .workspace(process.env.OPENHEX_WORKSPACE_SLUG!);

开通成员​

provisionMember 按 sp_user_ref 幂等开通：第一次调用创建成员，之后用同一个引用再调，返回的是同一个成员，created 为 false。

const member = await ws.provisionMember({
  sp_user_ref: 'user-42',   // 你系统里稳定、唯一的用户引用
  display_name: 'Ada',      // 可选
});
// → { member_id, billing_account_id, created: true }

所以你可以放心地在「用户每次登录」时调用它，而不必先判断是否开通过。

参数类型说明
sp_user_refstring你的用户引用。同一个引用永远对应同一个成员，不要用会变的值（如手机号）
display_namestring?成员的展示名
返回字段说明
member_id成员 id，也就是该成员的平台用户 id（与 listMembers 里的 user_id 相同）
billing_account_id成员的计费账户 id
created本次是否新建

仅接受工作区 API Key。用所有者登录态调用会得到 401 workspace API key required。

列出成员​

const { members } = await ws.listMembers();

for (const m of members) {
  console.log(m.sp_user_ref, m.status, m.balance);
}

每个成员包含：

字段说明
user_id成员 id（即 provisionMember 返回的 member_id）
billing_account_id计费账户 id
sp_user_ref你的用户引用（早期数据可能为 null）
statusactive 或 suspended
joined_at加入时间（ISO-8601 字符串）
balance当前积分余额

单次最多返回 500 个成员，目前没有分页参数。成员规模更大时，以你自己系统里的用户表为准，按需逐个开通 / 签发会话。

工作区 API Key 和工作区所有者的登录态都可以调用这个方法。

停用成员​

await ws.suspendMember(member.member_id);

停用是软操作：成员记录和余额都保留，状态变为 suspended。停用之后：

  • 再为该成员签发会话会被拒绝：403 member status is suspended；
  • 用同一个 sp_user_ref 再调 provisionMember 不会恢复它——返回 created: false，状态仍是 suspended；
  • 对已停用的成员再次调用 suspendMember 会得到 404 member not found，所以这个方法不是幂等的，重试时请把 404 当作「已经停用」处理。

⚠️ 停用不会吊销已经签发出去的会话令牌。 停用前签发的令牌在过期前仍然可用。需要「立刻踢下线」的场景，请把会话有效期设短（见 会话令牌），并在你自己的后端拒绝为该用户继续换发令牌。

Workspace API 目前没有「恢复成员」的接口。

常见错误​

状态码message原因
401workspace API key required用的不是工作区 API Key
403API key does not match workspaceKey 属于另一个工作区，和 slug 对不上
404member not found成员 id 不属于这个工作区，或已被停用

下一步​

  • 会话令牌 — 为成员签发令牌，让他和 Agent 对话
  • 积分 — 从工作区给成员发放积分
  • 方法参考 — 每个方法的鉴权、HTTP 路由与错误码