客户集成总览

Open4X 已从单一 API 网关扩展为一组可以组合使用的 AI、实时客服、消息推送、社交中控和第三方连接能力。本页面向准备接入 Open4X 的客户工程团队，说明新增能力、接入边界和当前可验证状态。

当前状态：staging 可用于技术联调；生产正式启用仍需通过支付、Provider、告警、观察期、SLA、DPA、价格和安全条款验收。staging 的额度和价格不是生产承诺。

新增能力

能力	当前状态	客户可以使用什么	主要接入方式
AI Model Gateway	MVP / staging 可测	OpenAI-compatible Models、Chat、Streaming、Embeddings、模型别名、预算和用量	服务端 API + `ai:invoke`
Widget 实时客服	staging POC 可测	固定版本 Loader、短期 Session、WebSocket、历史消息、断线补拉、消息幂等	服务端签发 Session + 浏览器 Widget
聚合事件读取	staging POC 可测	按租户读取所有 Widget 会话增量事件、稳定游标、HMAC、空查询不消耗事件额度	Bridge 服务端轮询 `/widget/events`
Webhook Push	Beta / staging 可测	一次请求推送到多个启用目标、Telegram 和 Generic Webhook、逐目标结果	`push:send` + target 配置
SocialOps	MVP	统一 Inbox、thread、状态、优先级、负责人、内部备注和回复队列	REST API + Console
Connected Accounts	Beta preparation	加密保存 API Key、Bot Token 和 OAuth 连接，服务复用凭据	Console Connections + OAuth
统一 API Key 与账务	Beta preparation	Scope、alias、来源 IP、每日额度、速率、并发、过期、轮换、撤销和审计	Console + API
异步 Job	MVP / 分服务可用	`pending`、`running`、`succeeded`、`failed` 等统一状态和回调约定	`/v1/jobs` + HMAC Callback
TRON 能量租赁	MVP / sandbox	报价、幂等下单、服务商履约、链上验证、退款状态机	`/v1/apps/tron`

五步接入流程

1. 创建服务实例

在 Console 创建所需服务，并为每个环境使用不同 alias：

text

ai-model:qwen122
bot
webhook-push:ops
socialops:support

alias 是客户侧配置的一部分，建议保存到环境变量或服务配置，不要硬编码在多个客户端。

2. 签发最小权限 Key

生产或 staging 都建议按职责拆分 Key：

Key	Scope	用途
Bridge Key	`bot:session:create`, `bot:events:read`, `bot:send`	Widget Session、事件同步、人工回复
AI Key	`ai:invoke`	模型列表、Chat、Streaming、Embeddings
Webhook Key	`push:send`	Webhook Push fan-out
SocialOps Key	`socialops:read`, `socialops:write`	Inbox 读取、事件写入和回复队列

API Key 只能保存在客户服务端或 Worker Secret。浏览器只能拿短期 Widget Session Token，不能拿平台 API Key。

3. 配置来源与额度

每把 Key 可以限制：

service_aliases：只能调用指定服务；
allowed_ips：限制固定出口 IP 或 CIDR；
daily_quota：UTC 日额度；
rate_limit_per_minute：每分钟请求数；
concurrency_limit：并发请求数；
expires_at：自动过期时间。

Key 创建、轮换、撤销、过期和策略拒绝都会写入审计元数据。明文只在创建或轮换时展示一次。

4. 先在 staging 验证

当前 staging 入口：

text

API:     https://open4x-gateway-staging.29498587.workers.dev
Console: https://openedge-console-staging.pages.dev
Widget:  https://open4x-widget-staging.pages.dev/widget.js

staging 默认关闭真实 AI、Telegram、Webhook、支付和其他高风险外部副作用。客户可以验证鉴权、请求格式、状态码、幂等、游标、HMAC、账务元数据和故障回退，但不能把 dry-run 当作真实 Provider 投递。

5. 通过生产门禁后再启用 Provider

生产启用需要真实 Provider 账户、Secret、回调、allowlist、支付配置、备份恢复、告警验证、连续观察期和业务/法务签字。没有正式证据清单时，生产发布门禁会阻断。

Session

客户服务端使用 Bridge Key 签发短期 Session：

http

POST /v1/apps/bot/widget/auth
X-API-Key: <bridge-key>
Content-Type: application/json

json

{
  "external_user_id": "customer-anon-001",
  "user_name": "Alice",
  "ttl_seconds": 1800
}

ttl_seconds 支持 900–3600 秒。external_user_id 应使用客户生成的稳定映射 ID，不要直接放邮箱、钱包地址或其他敏感数据。

浏览器只接收 session_token：

html

<script
  src="https://open4x-widget-staging.pages.dev/widget.js"
  data-token="SERVER_ISSUED_SESSION_TOKEN"
  data-gateway-url="https://open4x-gateway-staging.29498587.workers.dev">
</script>

实时消息与可靠同步

Widget 支持：

WebSocket ping/pong 和 connected / new_message 事件；
历史消息分页；
client_message_id 幂等，避免网络重试产生重复消息；
Session refresh、revoke 和过期关闭码 4001；
断线后通过消息接口或事件接口补拉。

服务端 Bridge 不需要为每个会话单独轮询，可以使用租户级聚合接口：

http

GET /v1/apps/bot/widget/events?cursor=<opaque_cursor>&limit=100
X-API-Key: <bridge-key>

不传 chat_id 时返回该租户所有 Widget 会话的增量事件。事件使用稳定的 (created_at, message_id) 游标，包含 event_id、conversation_id、chat_id、message_id、client_message_id、direction、visibility 和 created_at。

处理顺序应为：

text

读取事件 → 验证 HMAC → 按 event_id 去重 → 写入客户 outbox → 保存 next_cursor

staging 事件响应使用：

text

X-Open4X-Event-Timestamp: <unix_seconds>
X-Open4X-Event-Signature: sha256=<hex>

签名原文是 <timestamp>.<raw_response_body>，算法为 HMAC-SHA256。生产切换前应使用独立事件签名密钥。租户聚合事件额度独立于通用 API 日额度；空 data=[] 不消耗事件日额度，但仍受速率和并发限制。

AI 接入与客服辅助

AI 与基础客服解耦，客户可以选择：

模式	行为
关闭 AI	只使用 Widget、Inbox、人工客服和客户工单
客服辅助	AI 生成分类、摘要和回复建议，仅客服可见
AI 接待	AI 生成公开回复，复杂问题转人工

AI Gateway 支持 OpenAI-compatible 路径：

http

GET  /v1/apps/ai/qwen122/v1/models
POST /v1/apps/ai/qwen122/v1/chat/completions
POST /v1/apps/ai/qwen122/v1/embeddings

AI 请求建议携带 Idempotency-Key 和 X-Request-ID。响应可以包含预估成本、最终成本和 token 用量，客户可以按租户、用户、服务和请求 ID 做成本归因。

AI 不应直接读取或执行私密内容授权、退款、提现、钱包签名、封禁、结算或其他高风险动作。工具调用和 RAG 权限过滤需要由客户业务系统或后续产品模块负责。

Webhook Push 与 SocialOps

Webhook Push 适合把一条消息 fan-out 到多个已配置目标：

http

POST /v1/apps/webhook-push/ops/send
X-API-Key: <webhook-key>

每个 target 可以独立启用。全部成功返回 200，部分成功返回 207，全部失败返回 502。Telegram target 需要启用 Telegram Bot Connected Account 并配置 chat ID。

SocialOps 适合需要持续处理消息的客服、运营和开发协作场景：

统一 thread、Inbox、状态、优先级和负责人；
generic webhook、Telegram 和 GitHub 事件归一化；
公开回复和内部备注分离；
回复先进入 action 队列，再由 provider adapter 投递；
provider 失败保留审计错误，不静默丢失。

Slack、Discord、Teams、X/Twitter、Meta、Instagram、WhatsApp 和 LINE 需要逐个完成 provider 应用、OAuth、回调验证和出站能力配置，目前不能因为控制台有 provider 选项就视为已生产可用。

Knoveria 的 Telegram 当前状态

Knoveria 当前 staging 接入包没有包含已配置的 Telegram Bot Token，也没有完成 Telegram channel 绑定。因此客户看到的“没有 Telegram 机器人”是交付配置尚未开通，不是 Open4X 没有 Telegram 适配器。第一阶段 P0 仍以网页 Widget、WebSocket、Inbox 和工单同步为准，Telegram 属于后续渠道验收。

Open4X 的 Telegram + SocialOps 代码路径已经支持以下流程，但需要为 Knoveria 单独完成 Provider 开通：

在 Telegram 的 BotFather 创建 Bot，并通过安全渠道提供 Bot Token；
在 Console > Connections 创建 active 的 telegram-bot Connected Account；
创建并启用 socialops:support，绑定 Telegram channel、connected_account_id 和目标 chat_id；
创建或更新 Bot Service 后，由 Open4X 自动设置 webhook。staging 的 webhook 地址为：
text
```
https://open4x-gateway-staging.29498587.workers.dev/v1/apps/bot/webhook/platform
```
用户先向 Bot 发起会话，或将 Bot 加入目标群组并授予必要权限；入站消息随后进入 SocialOps thread 和 Inbox。

完成上述配置并开启真实 Provider 后，Knoveria 运维可以在 Console > SocialOps 中回复客户，也可以调用：

http

POST /v1/apps/socialops/support/threads/{thread_id}/replies
X-API-Key: <socialops-key>
Content-Type: application/json

回复先进入 action 队列，投递成功后记录 Telegram message_id；失败会保留审计错误。Bridge Key、AI Key 和 Webhook Push Key 不能替代 Telegram Bot Token，Bot Token 只能保存在加密的 Connected Account 中。

当前 staging 仍默认关闭 Telegram 的真实外部投递，所以配置完成后只能先做 dry-run，不能据此证明客户已经能收到真实 Telegram 回复。要进行真实联调，需要单独配置 Knoveria 的 staging Bot、channel、来源和 provider 开关，并完成入站、回复、失败和重试验证。Telegram Bot 也不能主动联系从未启动过 Bot 的任意用户。

第三方授权

Connected Accounts 支持一次配置、多个服务复用：

客户在 Console 的 Connections 中选择 provider；
使用 API Key、Bot Token 或 OAuth 完成授权；
Open4X 加密保存凭据，只返回脱敏状态；
服务实例通过 connected_account_id 引用连接；
撤销或停用连接后，后续请求立即停止使用该凭据。

OAuth provider 必须在目标环境配置 Client ID、Client Secret、回调 URL、来源和加密密钥。以 Discord 为例，未配置 DISCORD_CLIENT_ID 时，页面显示“OAuth 未配置”是配置缺失，不是用户重复授权可以解决的问题。

数据、安全与运营边界

API Key、Bot Token、Provider Key 不进入浏览器、日志、文档或 Git；
默认日志保存 request ID、服务、模型、token、状态、延迟和成本，不保存完整 prompt/response；
外部 URL 需要 HTTPS 和 SSRF 校验；
客户业务系统负责用户权限、订单、支付、工单和私密内容授权；
失败调用、超时和 Provider 不可用应由客户 outbox 或工单系统重试和回退；
生产前需要确定数据保留、删除、DPA、数据区域、状态页、SLA、维护通知和补偿规则。

客户集成总览

新增能力

推荐架构

五步接入流程

1. 创建服务实例

2. 签发最小权限 Key

3. 配置来源与额度

4. 先在 staging 验证

5. 通过生产门禁后再启用 Provider

Widget 实时客服接入

Session

实时消息与可靠同步

AI 接入与客服辅助

Webhook Push 与 SocialOps

Knoveria 的 Telegram 当前状态

第三方授权

数据、安全与运营边界

相关文档

客户集成总览 ​

新增能力 ​

推荐架构 ​

五步接入流程 ​

1. 创建服务实例 ​

2. 签发最小权限 Key ​

3. 配置来源与额度 ​

4. 先在 staging 验证 ​

5. 通过生产门禁后再启用 Provider ​

Widget 实时客服接入 ​

Session ​

实时消息与可靠同步 ​

AI 接入与客服辅助 ​

Webhook Push 与 SocialOps ​

Knoveria 的 Telegram 当前状态 ​

第三方授权 ​

数据、安全与运营边界 ​

相关文档 ​

客户集成总览

新增能力

推荐架构

五步接入流程

1. 创建服务实例

2. 签发最小权限 Key

3. 配置来源与额度

4. 先在 staging 验证

5. 通过生产门禁后再启用 Provider

Widget 实时客服接入

Session

实时消息与可靠同步

AI 接入与客服辅助

Webhook Push 与 SocialOps

Knoveria 的 Telegram 当前状态

第三方授权

数据、安全与运营边界

相关文档