copilotkit-setup

CopilotKit 设置

前置条件

实时文档（MCP）

该插件包含一个 MCP 服务（copilotkit-docs），它提供 search-docs 和 search-code 工具，用于查询实时的 CopilotKit 文档和源代码。

• Claude Code： 由插件的 .mcp.json 自动配置——无需设置。
• Codex： 需要手动配置。有关设置说明，请参阅 copilotkit-debug 技能。

环境

在开始设置之前，请确认：

1. Node.js >= 18（运行时使用的 fetch 全局变量所必需）
2. 一个 AI 提供方 API 密钥（以下之一：OPENAI_API_KEY、ANTHROPIC_API_KEY、GOOGLE_API_KEY）
3. 一个基于 React 的前端（Next.js App Router、Next.js Pages Router、Vite + React 或 Angular）
4. 一个能够运行该运行时的后端（通过 API 路由使用同一个 Next.js 应用，或一个独立的 Express/Hono 服务）

框架检测

在生成任何代码之前，通过检查项目根目录中的文件来检测项目的框架。有关完整的决策树，请参阅 references/framework-detection.md。

快速摘要：

信号文件	框架
next.config.{js,ts,mjs} + app/ 目录	Next.js App Router
next.config.{js,ts,mjs} + pages/ 目录	Next.js Pages Router
angular.json	Angular
vite.config.{js,ts} + package.json 中的 React 依赖	Vite + React

设置工作流

第 1 步：安装包

所有包都使用 @copilotkit 命名空间。v2 API 作为已发布包上的子路径导出提供。

前端 + 后端在同一个 Next.js 应用中：

npm install @copilotkit/react-core @copilotkit/runtime hono

仅前端：

npm install @copilotkit/react-core

仅后端运行时：

npm install @copilotkit/runtime hono

对于独立的 Express 后端，请安装 Express 适配器依赖项，而不是 hono：

npm install @copilotkit/runtime express dotenv zod
npm install -D @types/express tsx typescript

（createCopilotExpressHandler 内部启用了 CORS，因此你不需要自己安装 cors。示例资源中使用了 dotenv 和 zod。）

第 2 步：选择运行时模式，然后配置运行时

运行时是负责管理 Agent 执行的服务器端组件。详情请参阅 references/runtime-architecture.md。

在编写任何运行时代码之前先确定模式。 模式会改变运行时的构建方式，因此之后再改造意味着要重写此文件。

模式	线程状态	选择时机
Managed Intelligence（推荐）	持久化、托管	你希望线程在重启后仍然存在、托管入口、仪表盘或 Channels
自托管 SSE	内存中，重启后丢失	你不想要托管的依赖，并愿意自行负责持久化

询问用户想要哪一种，默认使用 managed Intelligence。清楚地说明前提条件，以便做出明智的选择：

Managed Intelligence 需要一个 CopilotKit 账户（免费；npx copilotkit login 会打开浏览器）和一个项目 API 密钥。作为交换，线程在重启和部署后仍然持久化，你可以使用仪表盘，并且 Slack/Teams Channels 将变为可用——Channels 在 SSE 模式下完全不可用。

自托管 SSE 需要的仅仅是一个 AI 提供商密钥。线程状态存在于处理该请求的进程的内存中，因此它会在重启后丢失，也不会在多个副本之间共享。本技能中的所有内容在 SSE 模式下都能正常工作；它是一条受支持的路径，而不是死胡同。

如果用户选择 managed Intelligence，请使用下面的 Intelligence 运行时代码块，然后完成第 6 步。如果他们选择 SSE，请使用 SSE 代码块并跳过第 6 步的服务器端接线。

有两种端点风格：

1. 多路由（Hono）——使用 createCopilotHonoHandler。需要一个捕获所有路由（在 Next.js 中为 [[...slug]]）。每个操作（run、connect、stop、info、transcribe、threads）都有自己的 HTTP 路径。
2. 单路由（Hono 或 Express）——使用 createCopilotHonoHandler({ ..., mode: "single-route" }) 或 createCopilotExpressHandler({ ..., mode: "single-route" })。所有操作都通过单个 POST 端点进行，并使用方法多路复用。

Next.js App Router（推荐：使用 Hono 的多路由）

创建 src/app/api/copilotkit/[[...slug]]/route.ts：

import {
  CopilotRuntime,
  createCopilotHonoHandler,
  InMemoryAgentRunner,
  BuiltInAgent,
} from "@copilotkit/runtime/v2";
import { handle } from "hono/vercel";

const agent = new BuiltInAgent({
  model: "openai/gpt-4o",
  prompt: "You are a helpful AI assistant.",
});

const runtime = new CopilotRuntime({
  agents: {
    default: agent,
  },
  runner: new InMemoryAgentRunner(),
});

const app = createCopilotHonoHandler({
  runtime,
  basePath: "/api/copilotkit",
});

export const GET = handle(app);
export const POST = handle(app);
// PATCH/DELETE are used by thread operations (useThreads); export them too
// so the multi-route handler can serve them when you enable Intelligence/threads.
export const PATCH = handle(app);
export const DELETE = handle(app);

使用 managed Intelligence 的 Next.js App Router

与上面相同的文件和相同的处理器；仅运行时构建方式不同。intelligence 是选择 Intelligence 模式的选项，并且需要与之配合的 identifyUser。

import {
  CopilotRuntime,
  CopilotKitIntelligence,
  createCopilotHonoHandler,
  BuiltInAgent,
} from "@copilotkit/runtime/v2";
import { handle } from "hono/vercel";

const agent = new BuiltInAgent({
  model: "openai/gpt-4o",
  prompt: "You are a helpful AI assistant.",
});

const intelligence = new CopilotKitIntelligence({
  // Server-side secret. `apiUrl`/`wsUrl` default to CopilotKit's managed
  // platform, so most projects set only the key.
  apiKey: process.env.CPK_INTELLIGENCE_API_KEY!,
});

const runtime = new CopilotRuntime({
  agents: { default: agent },
  intelligence,
  // REQUIRED in Intelligence mode: it decides whose threads these are. Resolve a
  // real authenticated user from the request -- with a hardcoded id, every visitor
  // shares one thread history.
  identifyUser: (request) => resolveUserFromSession(request),
});

const app = createCopilotHonoHandler({
  runtime,
  basePath: "/api/copilotkit",
});

export const GET = handle(app);
export const POST = handle(app);
export const PATCH = handle(app);
export const DELETE = handle(app);

重要提示：

• 不要传递 runner。 Intelligence 模式会自行提供 IntelligenceAgentRunner；传递 InMemoryAgentRunner 正是让线程保留在内存中的原因。
• identifyUser 不是可选的。 它是线程归属的边界。像 () => ({ id: "demo", name: "Demo" }) 这样的桩代码对于本地原型来说没问题，但对于任何多用户场景都是错误的。
• apiUrl 和 wsUrl 是分开的主机。 它们默认为 https://api.intelligence.copilotkit.ai 和 wss://realtime.intelligence.copilotkit.ai。实时平面不能通过交换协议方案从 API 平面推导出来，因此请两者都覆盖或都不覆盖——只覆盖其中一个会使两个平面指向不同的部署。

Next.js App Router（替代方案：单路由）

创建 src/app/api/copilotkit/route.ts：

import {
  CopilotRuntime,
  createCopilotHonoHandler,
  InMemoryAgentRunner,
  BuiltInAgent,
} from "@copilotkit/runtime/v2";
import { handle } from "hono/vercel";

const agent = new BuiltInAgent({
  model: "openai/gpt-4o",
  prompt: "You are a helpful AI assistant.",
});

const runtime = new CopilotRuntime({
  agents: {
    default: agent,
  },
  runner: new InMemoryAgentRunner(),
});

const app = createCopilotHonoHandler({
  runtime,
  basePath: "/api/copilotkit",
  mode: "single-route",
});

export const POST = handle(app);

前端 provider 会自动协商这一点；仅为了显式固定单路由传输时，才在其上设置 useSingleEndpoint（参见第 3 步）。

独立 Express 服务器

创建 src/index.ts：

import express from "express";
import { CopilotRuntime, BuiltInAgent } from "@copilotkit/runtime/v2";
import { createCopilotExpressHandler } from "@copilotkit/runtime/v2/express";

const agent = new BuiltInAgent({
  model: "openai/gpt-4o",
});

const runtime = new CopilotRuntime({
  agents: {
    default: agent,
  },
});

const app = express();

app.use(
  "/api/copilotkit",
  createCopilotExpressHandler({
    runtime,
    basePath: "/",
    mode: "single-route",
  }),
);

const port = Number(process.env.PORT ?? 4000);
app.listen(port, () => {
  console.log(
    `CopilotKit runtime listening at http://localhost:${port}/api/copilotkit`,
  );
});

对于多路由 Express，省略 mode 选项（多路由是默认值）——createCopilotExpressHandler 对两种风格都是同一个工厂（从 @copilotkit/runtime/v2/express 导入）。

独立 Hono 服务器（非 Vercel）

import {
  CopilotRuntime,
  createCopilotHonoHandler,
  BuiltInAgent,
} from "@copilotkit/runtime/v2";
import { serve } from "@hono/node-server";

const runtime = new CopilotRuntime({
  agents: {
    default: new BuiltInAgent({ model: "openai/gpt-4o" }),
  },
});

const app = createCopilotHonoHandler({
  runtime,
  basePath: "/api/copilotkit",
});

serve({ fetch: app.fetch, port: 8787 });

需要 @hono/node-server：

npm install hono @hono/node-server

步骤 3：设置前端 provider

使用来自 @copilotkit/react-core/v2 的 CopilotKit 包裹你的应用。

选择哪个 provider 组件？ 始终使用从 @copilotkit/react-core/v2 导入的 CopilotKit。它是 v1 与 v2 之间的兼容桥梁，也是其他 provider API 的严格超集。请不要使用从包根目录导入的 CopilotKit（@copilotkit/react-core，旧的 v1），也不要使用来自 /v2 的 CopilotKitProvider（功能子集）。

重要： 在你的根布局中导入样式表：

import "@copilotkit/react-core/v2/styles.css";

Next.js App Router

在 src/app/page.tsx 中（或某个客户端组件中）：

"use client";

import { CopilotKit, CopilotChat } from "@copilotkit/react-core/v2";

export default function Home() {
  return (
    // No useSingleEndpoint: the provider negotiates the transport, so it
    // matches the multi-route backend above (the default) or a single-route
    // one. Pass the prop only to pin one mode deliberately.
    <CopilotKit runtimeUrl="/api/copilotkit">
      <div style={{ height: "100vh" }}>
        <CopilotChat />
      </div>
    </CopilotKit>
  );
}

连接到外部 runtime

当 runtime 运行在单独的服务器上时（例如，运行在 4000 端口的 Express）：

<CopilotKit runtimeUrl="http://localhost:4000/api/copilotkit" useSingleEndpoint>
  {children}
</CopilotKit>

省略 useSingleEndpoint 会让 provider 协商传输方式，这对任一 handler 模式都适用。仅在需要固定为单路由传输时（createCopilotHonoHandler 或 createCopilotExpressHandler 配合 mode: "single-route"）将其设为 true，或设为 false 以固定为多路由 REST 路由。

CopilotKit 关键 props

Prop	Type	Description
runtimeUrl	string	CopilotKit runtime 端点的 URL
useSingleEndpoint	boolean	省略以协商传输方式（适用于任一 handler 模式）；true 固定为单路由，false 固定为多路由
headers	Record<string, string> | (() => Record<string, string>)	随每个请求发送的自定义 headers。函数形式会按请求求值（适用于动态认证 token）。
credentials	RequestCredentials	Fetch 凭证模式（例如，使用 "include" 以携带 cookies）
showDevConsole	boolean	显示开发者控制台。省略它以使用默认行为（仅在 localhost 上显示）
renderToolCalls	ReactToolCallRenderer[]	工具调用 UI 的自定义渲染器
frontendTools	ReactFrontendTool[]	前端定义的工具（useFrontendTool 的声明式替代方案）
onError	(event) => void	全局错误处理器

步骤 4：添加聊天 UI 组件

CopilotKit 提供三种预构建的聊天布局（全部从 @copilotkit/react-core/v2 导入）：

Component	Usage
CopilotChat	内联聊天，填满其容器
CopilotSidebar	可折叠的侧边栏面板
CopilotPopup	浮动弹出式组件

使用侧边栏的示例：

import { CopilotKit, CopilotSidebar } from "@copilotkit/react-core/v2";

<CopilotKit runtimeUrl="/api/copilotkit" useSingleEndpoint={false}>
  <YourApp />
  <CopilotSidebar
    defaultOpen
    width="420px"
    labels={{
      modalHeaderTitle: "AI Assistant",
      chatInputPlaceholder: "Ask me anything...",
    }}
  />
</CopilotKit>;

第 5 步：设置环境变量

提供商的 API 密钥属于机密信息。请将它们存放在环境变量中——切勿硬编码到源码中，也不要提交到版本控制系统。创建一个 .env.local（Next.js）或 .env 文件：

OPENAI_API_KEY=<your-openai-api-key>

确保你的 .gitignore 排除了环境变量文件（.env、.env.local、.env*.local），这样密钥就永远不会被提交。在生产环境中，请通过平台的密钥管理器（Vercel/Netlify 环境变量、AWS Secrets Manager 等）提供密钥，而不要使用已检入的文件。

BuiltInAgent 会根据模型前缀自动从这些环境变量中解析 API 密钥：

• openai/* 模型读取 OPENAI_API_KEY
• anthropic/* 模型读取 ANTHROPIC_API_KEY
• google/* 模型读取 GOOGLE_API_KEY

如果你需要显式传递 apiKey，请始终从环境中获取（apiKey: process.env.OPENAI_API_KEY）——切勿内联字面量密钥。

第 6 步：连接到 CopilotKit Intelligence

仅当用户在步骤 2 中选择可自托管 SSE 时，才跳过此步骤。

Intelligence 只需要一个凭据，并且它是服务器端的。它不会以任何形式到达浏览器，也没有任何提供商 prop 会配置它。

凭据	所在位置	是密钥吗？	用途
项目 API 密钥（cpk-...）	仅服务器端	是	运行时通过它向 Intelligence 进行身份验证

不要去找 publicApiKey 或 publicLicenseKey。它们会将无运行时的客户端指向 CopilotKit Cloud，那是另一个产品。

1. 登录并创建项目。

   npx copilotkit login
   npx copilotkit project select
   

   login 会打开浏览器并存储本地 CLI 会话。project select 会选择或创建一个托管项目，并将其记录到 .copilotkit/project.json。如果版本不同，可用 npx copilotkit --help 验证可用命令。

2. 设置服务器端项目 API 密钥。 project select 会提供一个；你也可以从仪表板复制它。

   # .env.local (Next.js) or .env
   CPK_INTELLIGENCE_API_KEY=cpk-...
   

   这是一项机密信息。它故意没有 NEXT_PUBLIC_/VITE_ 前缀——加上前缀会将其发送到浏览器。它由你在步骤 2 中接入的 CopilotKitIntelligence 客户端读取。

   CPK_INTELLIGENCE_API_KEY 是规范名称——它正是 copilotkit project select 所提供的，也是每个 CopilotKit 界面所记录的。COPILOTKIT_API_KEY 是已弃用的别名，一些较旧的示例仍会读取它。

3. 确认接线正确。

   npx copilotkit verify
   

   它会报告是否已选择项目、密钥是否加载并通过身份验证、运行时是否确实在使用该凭据，以及运行时是否提供已保存线程所需的线程路由。

4. 确认持久线程确实可用。 发送一条消息，重启开发服务器，然后重新加载。该线程应该仍然存在。如果不存在，说明运行时仍处于 SSE 模式——检查是否传入了 intelligence，以及是否有 runner 覆盖了它。

请参阅 references/telemetry-setup.md，了解 Intelligence 启用了什么、连接它的 CLI 流程，以及如何选择退出。

连接 Slack 或 Microsoft Teams

频道让 Agent 可以在 Slack 或 Teams 中作答。它们需要 Intelligence 运行时——SSE 模式下不提供 channels——以及一个长期运行的主机，因为激活会打开一个持久连接。

为此请使用 copilotkit-channels 技能。它涵盖如何声明一个 Channel、长期运行主机的要求，以及哪些挂载点会自行启动激活、哪些需要显式调用 channels.ready()。它建立在本步骤的接线基础之上。

对于新的托管 Teams 应用，请先在 Intelligence 中创建 Channel 草稿，并使用推荐的由浏览器生成的 Fast CLI 命令（channels add --project-id … --channel-id … --adapter teams --provision）或对等的 Guided 手动路径。不要搭建 Azure Bot 资源，也不要在项目中放置 Microsoft 凭据、自定义图标或生成的包。提供方的 Created and installed 结果与这部分代码是分开的；只有运行中的主机加上一次真实的 Teams 交互，才能端到端验证该集成。

第 7 步：验证设置

1. 启动开发服务器
2. 在浏览器中打开应用
3. 聊天 UI 应当能够渲染并连接到运行时
4. 发送一条测试消息——你应当收到 AI 响应
5. 检查运行时的 info 端点，确认它报告了可用的 Agent。对于多路由处理器，这是 GET /api/copilotkit/info；对于单路由处理器（mode: "single-route"，例如 Express 示例），这是向基础路径发送的 POST，请求体为 { "method": "info" }（普通的 GET 不会返回 Agent 信息——Hono 单路由处理器会应答 405，而 Express 单路由路由器没有 GET 路由，因此会落到 404）

安全注意事项

在接线真实部署时，请牢记以下几点：

• 密钥留在服务端并放在环境变量中。 提供方 API 密钥（OPENAI_API_KEY 等）由服务端的运行时/Agent 读取。切勿将它们暴露给浏览器、硬编码或提交——请将它们存储在环境变量或密钥管理器中（参见第 5 步）。CopilotKit Intelligence 不增加任何客户端侧价值：其凭据由服务端的运行时读取。
• 将所有聊天输入视为不可信。 聊天消息从前端经由 CopilotRuntime 端点流入 Agent 的大模型上下文。它们由用户控制，可能尝试提示词注入——包括通过 Agent 获取的内容（网页、文档、工具结果）进行的间接注入。不要假设模型只会做你的系统提示词所意图的事情。
• 为服务端工具授予最小权限。 defineTool 的 execute 函数以你的服务器的权限运行。校验每一个参数（zod 的 parameters schema 是你的第一道关卡），将每个工具限定在其所需的最窄操作范围内，并对任何敏感操作（数据库写入、支付、文件访问）在 execute 函数内部强制执行你自己的授权，而不是信任模型会正确调用它。
• 对运行时端点进行身份验证。 运行时路由默认是一个公开的 HTTP 端点。请将你的应用的身份验证置于其前面，这样只有经过授权的用户才能驱动 Agent 并消耗提供方额度。

快速参考

包映射

包	用途
@copilotkit/react-core	React 组件、hooks、provider（从 @copilotkit/react-core/v2 导入）
@copilotkit/runtime	运行时、端点工厂、Agent runners、BuiltInAgent、defineTool（从 @copilotkit/runtime/v2 导入）
@copilotkit/shared	共享工具、logger、类型

端点工厂函数

函数	导入	框架	模式
createCopilotHonoHandler	@copilotkit/runtime/v2	Next.js App Router、Hono 独立运行	"multi-route"（默认）或 mode: "single-route"
createCopilotExpressHandler	@copilotkit/runtime/v2/express	Express 独立运行	"multi-route"（默认）或 mode: "single-route"

createCopilotEndpoint、createCopilotEndpointSingleRoute、createCopilotEndpointExpress 和 createCopilotEndpointSingleRouteExpress 这些名称是上述两个工厂的已弃用别名。请优先使用带 mode 选项的 handler 工厂。

运行时类

类	使用场景
CopilotRuntime	兼容性垫片；自动选择 SSE 或 Intelligence 模式
CopilotSseRuntime	显式 SSE 模式（默认，内存中的线程）
CopilotIntelligenceRuntime	Intelligence 模式（持久化线程、实时事件、Channels）

Channels 需要 Intelligence 运行时和长时间运行的主机。请参阅 copilotkit-channels 技能。

Agent 运行器

运行器	描述
InMemoryAgentRunner	默认。将线程状态存储在进程内存中。适用于开发和单实例部署。
IntelligenceAgentRunner	与 CopilotIntelligenceRuntime 自动配合使用。通过 WebSocket 连接到 CopilotKit Intelligence。

支持的模型（BuiltInAgent）

格式："provider/model-name" 字符串或 Vercel AI SDK 的 LanguageModel 实例。

OpenAI： openai/gpt-5、openai/gpt-5-mini、openai/gpt-4.1、openai/gpt-4.1-mini、openai/gpt-4.1-nano、openai/gpt-4o、openai/gpt-4o-mini、openai/o3、openai/o3-mini、openai/o4-mini

Anthropic： anthropic/claude-sonnet-4-6、anthropic/claude-sonnet-4-5、anthropic/claude-opus-4-8、anthropic/claude-haiku-4-5

Google： google/gemini-2.5-pro、google/gemini-2.5-flash、google/gemini-2.5-flash-lite

任何 string 都会被接受（用于自定义/未列出的模型）；provider 从 / 之前的前缀解析。