OpenAI ChatKit 入门与托管集成

ChatKit提供可定制的嵌入式聊天体验，可用于内部知识库、人力资源入职、研究、购物与日程安排、故障排查、财务规划或客户支持等助手。

通过可嵌入界面组件、可定制提示词、工具调用支持、附件及思维链可视化等能力，可以构建智能体体验，无需重新实现聊天界面。

概览

选择两条ChatKit路径之一：

自定义服务器集成：在自有基础设施运行ChatKit，使用ChatKit Python SDK连接智能体服务，包括以Agents SDK构建的服务；用组件构建前端。
现有Agent Builder托管集成：已经通过Agent Builder工作流使用ChatKit的用户，可以在Agent Builder过渡期继续使用该托管工作流。

Agent Builder正在弃用，计划于2026年11月30日关闭，ChatKit仍可用。新增应用或迁移规划应采用ChatKit高级集成，连接自己的服务端智能体实现；过渡指南见从Agent Builder迁移。

开始使用ChatKit

自定义服务器集成：结合服务器与ChatKit SDK，自定义聊天体验。
现有托管工作流：在过渡期连接已有Agent Builder工作流。

在前端嵌入ChatKit

只有已存在支撑ChatKit的Agent Builder工作流时，才使用这条路径。新应用或在关闭前迁移的应用，应通过高级集成连接自有服务端智能体实现。

与现有托管工作流集成大体分三步：在Agent Builder仍可用时打开已有工作流，然后配置ChatKit并添加功能。

OpenAI托管ChatKit的前端与托管工作流集成示意图。

1. 使用已有托管工作流

在Agent Builder打开已有工作流，取得工作流ID。过渡规划见迁移指南。嵌入前端的聊天会指向所选工作流。

2. 在产品中配置ChatKit

需要创建ChatKit会话与服务端端点、传入工作流ID、交换客户端秘密，再添加嵌入脚本。

安全要求：创建会话必须提供user参数，每位最终用户应有独立标识。服务器必须先认证应用用户，再把其唯一标识传给该参数。

在服务器生成客户端令牌。下例启动服务，通过OpenAI API创建ChatKit会话并返回会话的客户端秘密：

来源示例 1（python）：

## [中文] 示例1：2. 在产品中配置ChatKit。
## [中文] 服务端先验证应用Bearer令牌，从环境中的演示映射取得稳定用户ID，再用服务器API密钥创建ChatKit会话。
## [中文] wf_123须替换为已有工作流；只返回client_secret。生产应改用真实应用认证，不能信任前端自行声称的user。
## Replace the illustrative IDs and URLs below with your own resource values.
import hmac
import json
import os
from typing import Annotated

import requests
from fastapi import Depends, FastAPI, HTTPException
from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
from pydantic import BaseModel


api_key = os.environ["OPENAI_API_KEY"]
workflow_id = "wf_123"
authenticated_users: dict[str, str] = json.loads(
    os.environ["CHATKIT_AUTHENTICATED_USERS"]
)
bearer_auth = HTTPBearer(auto_error=False)


def get_authenticated_user_id(
    credentials: Annotated[
        HTTPAuthorizationCredentials | None,
        Depends(bearer_auth),
    ],
) -> str:
    if credentials is not None:
        for token, user_id in authenticated_users.items():
            if hmac.compare_digest(credentials.credentials, token):
                return user_id
    raise HTTPException(status_code=401, detail="Invalid authentication token")


class ChatKitSession(BaseModel):
    client_secret: str


app = FastAPI()


@app.post("/api/chatkit/session")
def create_chatkit_session(
    user_id: Annotated[str, Depends(get_authenticated_user_id)],
):
    response = requests.post(
        "https://api.openai.com/v1/chatkit/sessions",
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
            "OpenAI-Beta": "chatkit_beta=v1",
        },
        json={
            "workflow": {"id": workflow_id},
            "user": user_id,
        },
        timeout=30,
    )
    response.raise_for_status()
    session = ChatKitSession.model_validate(response.json())
    return {"client_secret": session.client_secret}

来源示例 2（ruby）：

## [中文] 示例2：2. 在产品中配置ChatKit。
## [中文] 启动仅监听本机的WEBrick服务；只处理指定POST端点，校验Bearer令牌后创建会话，返回客户端秘密。
## [中文] 环境映射用于演示，错误令牌返回401、上游异常返回502；真实部署的令牌比较、超时及刷新须另行验证。
## Replace the illustrative IDs and URLs below with your own resource values.
require "json"
require "net/http"
require "openssl"
require "webrick"

api_key = ENV.fetch("OPENAI_API_KEY")
workflow_id = "wf_123"
## Demo authentication mapping. Replace this with your application's session authentication.
authenticated_users = JSON.parse(ENV.fetch("CHATKIT_AUTHENTICATED_USERS"))
server = WEBrick::HTTPServer.new(
  BindAddress: "127.0.0.1", Port: Integer(ENV.fetch("PORT", "8000")),
  AccessLog: [], Logger: WEBrick::Log.new($stderr, WEBrick::BasicLog::WARN)
)
server.mount_proc("/api/chatkit/session") do |request, response|
  response["Content-Type"] = "application/json"
  response["Cache-Control"] = "no-store"
  unless request.path == "/api/chatkit/session" && request.request_method == "POST"
    response.status = 405
    response.body = JSON.generate(error: "Use POST /api/chatkit/session")
    next
  end
  token = request["Authorization"].to_s.delete_prefix("Bearer ")
  user = authenticated_users.find do |credential, _id|
    request["Authorization"].to_s.start_with?("Bearer ") &&
      OpenSSL.secure_compare(credential, token)
  end
  unless user
    response.status = 401
    response.body = JSON.generate(error: "Invalid authentication token")
    next
  end
  uri = URI("https://api.openai.com/v1/chatkit/sessions")
  upstream = Net::HTTP::Post.new(uri)
  upstream["Authorization"] = "Bearer #{api_key}"
  upstream["Content-Type"] = "application/json"
  upstream["OpenAI-Beta"] = "chatkit_beta=v1"
  upstream.body = JSON.generate(workflow: { id: workflow_id }, user: user.fetch(1))
  begin
    result = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true, open_timeout: 10, read_timeout: 30) do |http|
      http.request(upstream)
    end
    result.value
    secret = JSON.parse(result.body).fetch("client_secret")
    raise "Missing session secret" unless secret.is_a?(String) && !secret.empty?

    response.body = JSON.generate(client_secret: secret)
  rescue
    response.status = 502
    response.body = JSON.generate(error: "Unable to create a ChatKit session")
  end
end
trap("INT") { server.shutdown }
trap("TERM") { server.shutdown }
puts("http://127.0.0.1:#{server.config[:Port]}/api/chatkit/session")
$stdout.flush
server.start

Ruby需先运行gem install webrick。启动服务前，将wf_123换成自己的工作流ID，设置OPENAI_API_KEY与CHATKIT_AUTHENTICATED_USERS；后者是应用Bearer令牌到稳定用户ID的JSON映射。生产中应换成应用自己的认证或会话查询。

在服务端向会话端点提供工作流ID与秘密密钥。客户端秘密是ChatKit前端打开或刷新聊天会话的凭证，不应将其存储起来，而应立即交给ChatKit客户端库。相关代码见chatkit-js仓库。

Go使用go get github.com/openai/openai-go/v3@v3.70.0；Java添加Maven依赖com.openai:openai-java:4.75.1。以下创建会话令牌：

来源示例 3（javascript）：

// [中文] 示例3：2. 在产品中配置ChatKit。
// [中文] 在服务器创建ChatKit会话，检查HTTP响应与client_secret；示意工作流ID须替换。
// [中文] 参数名deviceId沿用来源，但传入值必须来自已认证的稳定用户身份；不能直接信任客户端提供的设备ID，API密钥不下发浏览器。
export default async function getChatKitSessionToken(deviceId) {
  const apiKey = process.env.OPENAI_API_KEY;
  if (!apiKey) {
    throw new Error("OPENAI_API_KEY is required");
  }

  const response = await fetch("https://api.openai.com/v1/chatkit/sessions", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "OpenAI-Beta": "chatkit_beta=v1",
      Authorization: `Bearer ${apiKey}`,
    },
    body: JSON.stringify({
      workflow: { id: "wf_68df4b13b3588190a09d19288d4610ec0df388c3983f58d1" },
      user: deviceId,
    }),
  });

  if (!response.ok) {
    throw new Error(
      `Failed to create a ChatKit session: ${response.status} ${await response.text()}`
    );
  }

  const { client_secret } = await response.json();

  if (!client_secret) {
    throw new Error("ChatKit session response did not include client_secret");
  }

  return client_secret;
}

来源示例 4（go）：

// [中文] 示例4：2. 在产品中配置ChatKit。
// [中文] 在完成应用认证后调用此Go函数，以认证上下文中的稳定用户ID创建会话；不用客户端设备ID冒充用户。
// [中文] 返回client_secret或错误；需准备context、openai导入、客户端和实际工作流，原片段不是完整main程序。
// Call after authenticating the request. Pass the user's stable ID from your
// server-side authentication context, never a client-supplied device ID.
func getChatKitSessionToken(ctx context.Context, client openai.Client, authenticatedUserID string) (string, error) {
    // Replace this illustrative workflow ID with your published workflow.
    session, err := client.Beta.ChatKit.Sessions.New(ctx, openai.BetaChatKitSessionNewParams{
        User: authenticatedUserID,
        Workflow: openai.ChatSessionWorkflowParam{
            ID: "wf_68df4b13b3588190a09d19288d4610ec0df388c3983f58d1",
        },
    })
    if err != nil {
        return "", err
    }
    return session.ClientSecret, nil
}

来源示例 5（java）：

// [中文] 示例5：2. 在产品中配置ChatKit。
// [中文] Java在服务端用已认证用户ID创建会话并返回clientSecret；替换示意工作流ID。
// [中文] 这是含静态方法的嵌入片段，需要适当的类、依赖及认证调用方，不应直接当作完整独立Java文件。
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.chatkit.sessions.*;
import com.openai.models.beta.chatkit.threads.ChatSessionWorkflowParam;

// Call after authenticating the request. Pass the user's stable ID from your
// server-side authentication context, never a client-supplied device ID.
static String getChatKitSessionToken(OpenAIClient client, String authenticatedUserId) {
  // Replace this illustrative workflow ID with your published workflow.
  return client
      .beta()
      .chatkit()
      .sessions()
      .create(
          SessionCreateParams.builder()
              .user(authenticatedUserId)
              .workflow(
                  ChatSessionWorkflowParam.builder()
                      .id("wf_68df4b13b3588190a09d19288d4610ec0df388c3983f58d1")
                      .build())
              .build())
      .clientSecret();
}

安装React绑定：在项目目录执行：

来源示例 6（bash）：

## [中文] 示例6：2. 在产品中配置ChatKit。
## [中文] 在前端项目安装ChatKit React绑定；此命令只安装依赖，不创建后端会话。
   npm install @openai/chatkit-react

加入ChatKit JS脚本：把以下片段放入页面<head>或其他脚本加载位置，由浏览器获取并运行ChatKit：

来源示例 7（html）：

<!-- [中文] 示例7：2. 在产品中配置ChatKit。 -->
<!-- [中文] 由浏览器从官方CDN异步加载ChatKit脚本；本段是页面HTML，不包含服务器API密钥。 -->
<script
src="https://cdn.platform.openai.com/deployments/chatkit/chatkit.js" rel="external nofollow" 
async
></script>

在界面渲染ChatKit：向React的MyChat组件传入getAppAuthToken，由它返回当前用户的Bearer令牌。使用JavaScript片段时，也要在其作用域提供同名函数。代码把该凭证发送到自有服务器，取得客户端秘密，再挂载连接工作流的聊天组件。

来源示例 8（javascript）：

// [中文] 示例8：2. 在产品中配置ChatKit。
// [中文] 找到已加载的ChatKit元素，配置getClientSecret，用getAppAuthToken取得应用令牌，再请求自有服务器。
// [中文] 先检查HTTP是否成功，再返回client_secret；还需准备my-chat元素、脚本和getAppAuthToken。
const chatkit = document.getElementById("my-chat");
if (
  !chatkit ||
  !("setOptions" in chatkit) ||
  typeof chatkit.setOptions !== "function"
) {
  throw new Error("ChatKit element not found.");
}

chatkit.setOptions({
  api: {
    async getClientSecret() {
      const appAuthToken = await getAppAuthToken();
      const res = await fetch("/api/chatkit/session", {
        method: "POST",
        headers: {
          Authorization: `Bearer ${appAuthToken}`,
          "Content-Type": "application/json",
        },
      });
      if (!res.ok) {
        throw new Error(`ChatKit session request failed: ${res.status}`);
      }
      const { client_secret } = await res.json();
      return client_secret;
    },
  },
});

来源示例 9（tsx）：

// [中文] 示例9：2. 在产品中配置ChatKit。
// [中文] React使用useChatKit取得control，再渲染600px高、320px宽的ChatKit组件；返回元素按同页HTML恢复。
// [中文] getAppAuthToken应返回当前已认证用户的应用令牌。existing分支中的会话刷新尚待实现，来源片段也未检查res.ok，不能宣称刷新或错误处理已经完整。
import { ChatKit, useChatKit } from '@openai/chatkit-react';

   export function MyChat({ getAppAuthToken }) {
     const { control } = useChatKit({
       api: {
         async getClientSecret(existing) {
           if (existing) {
             // implement session refresh
            }

           const appAuthToken = await getAppAuthToken();
           const res = await fetch('/api/chatkit/session', {
             method: 'POST',
             headers: {
               'Authorization': 'Bearer ' + appAuthToken,
               'Content-Type': 'application/json',
             },
           });
           const { client_secret } = await res.json();
           return client_secret;
         },
       },
     });

     return <ChatKit control={control} className="h-[600px] w-[320px]" />;
   }

3. 构建与迭代

继续了解主题定制、组件与动作，或使用下面资源测试聊天、调整提示词、添加组件和工具。

构建实现

GitHub上的ChatKit文档：认证、主题与定制。
ChatKit Python SDK：服务端存储、访问控制、工具及其他后端能力。
ChatKit JS SDK：JavaScript仓库。

探索ChatKit界面

chatkit.world：交互演示。
Widget Builder：浏览可用组件。
ChatKit Playground：通过交互演示边做边学。

查看可运行示例

GitHub示例：完整实现与灵感。
入门应用仓库：克隆可运行模板。

后续步骤

完成ChatKit实现后，通过评测优化。新应用，或希望把现有应用从Agent Builder托管工作流迁出的情况，继续阅读高级集成。