CopilotKit 保姆级部署教程：3 步给你的 Web 应用接入 AI 智能体

CopilotKit（仓库 CopilotKit/CopilotKit，MIT 协议，最近提交 2026-10-29）是开源的"把 AI 智能体放到真实用户面前"的 React 组件库。你已经用 LangGraph / CrewAI / Pydantic AI 写好了智能体？CopilotKit 帮你把聊天窗、生成式 UI、共享状态、人机确认直接嵌进 React / Angular / Vue / React Native / Slack / Teams 里。它背后是 AG-UI 协议——Google、Microsoft、AWS、LangChain 都在用。

本文严格对照官方 README 给出一键脚手架与手写 Next.js 两种接入方式。

一、项目介绍与适用场景

CopilotKit 的定位：你的智能体负责推理和执行，CopilotKit 负责把它的工作变成产品体验。事件通过 AG-UI 协议流式传输，智能体能边做边显示、读到用户正在看什么、调用会渲染成 UI 的工具、在关键步骤停下来等人确认。

适用场景：

SaaS 产品：给后台加一个侧边栏 Copilot，让 AI 帮用户改数据、填表单；
内部工具：让业务方用自然语言查数据库、生成报表；
多渠道：一套 JSX 同时渲染成 React 网页、Slack Block Kit、Teams Adaptive Cards。

二、核心功能逐条拆解

现成聊天组件：CopilotSidebar 一行挂上，可替换插槽。
生成式 UI：智能体直接渲染你写的 React 组件，或走 A2UI 规范。
共享状态：Agent 和 UI 读写同一个 state 层。
人机协同（HITL）：智能体在执行前暂停等用户确认。
前端工具：让智能体在你的应用里调用前端函数。
AG-UI 流式会话：跨设备、跨会话续聊，生成式 UI 不丢。
语音 & WebMCP：支持语音输入，把你的应用动作暴露给浏览器智能体。
Inspector：localhost 浮层调试线程与智能体。
多框架后端：LangGraph、CrewAI、Mastra、Google ADK、PydanticAI 都能接。

三、全套官方链接

类型	链接
GitHub 仓库	https://github.com/CopilotKit/CopilotKit
官方文档	https://docs.copilotkit.ai/
官方示例	https://www.copilotkit.ai/examples
License	MIT（README 徽章明确）

四、硬件与环境前置要求

Node.js 18+（推荐 20 LTS）；
npm / pnpm / bun；
一个 OpenAI Key（或其他兼容模型 Key）；
已有或新建一个 React / Next.js 项目。

五、多平台部署步骤

5.1 方式一：官方脚手架（最快）

官方 README 给出的新工程命令：

npx copilotkit@latest create

这条命令会在一个独立目录里脚手架一个全新应用，不会动你已有项目。

如果是把 CopilotKit 加进现有项目，官方推荐让编程智能体做：

npx --yes copilotkit@latest onboard start

官方还提供给编程智能体装技能：

npx copilotkit@latest skills install

5.2 方式二：手写 Next.js 三文件接入

官方 README 给出的完整三文件示例。

第一步：装依赖：

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

第二步：.env.local 填模型 Key：

OPENAI_API_KEY=your_openai_api_key

第三步：写后端路由 app/api/copilotkit/[[...slug]]/route.ts（官方原文）：

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

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

const handler = createCopilotRuntimeHandler({
  runtime,
  basePath: "/api/copilotkit",
});
export { handler as GET, handler as POST, handler as PATCH, handler as DELETE };

第四步：写前端 app/page.tsx（官方原文）：

"use client";
import { CopilotKitProvider, CopilotSidebar } from "@copilotkit/react-core/v2";
import "@copilotkit/react-core/v2/styles.css";

export default function Page() {
  return (
    <CopilotKitProvider runtimeUrl="/api/copilotkit">
      <main>
        <h1>Your App</h1>
        <CopilotSidebar />
      </main>
    </CopilotKitProvider>
  );
}

5.3 接入已有智能体后端

官方 README 说明：如果你已经在用 LangGraph、CrewAI、Mastra 等，把 BuiltInAgent 换成对应框架的 agent 即可，参考 https://docs.copilotkit.ai/quickstart 。

5.4 Docker / 服务端部署

官方 README 未提供独立 Docker 镜像；CopilotKit 是前端+运行时库，你把它当作普通 Next.js 应用部署即可（Vercel / Node 服务器 / 容器均可）。

六、配置文件全部参数解释

参数名	作用	可选值	默认值	配置示例	改错后果
`OPENAI_API_KEY`	OpenAI 模型 Key	sk-xxx	无	`.env.local` 里填	不填则 BuiltInAgent 401
`model`	模型选择	`openai:gpt-5.4-mini` 等	无	`"openai:gpt-5.4-mini"`	模型名错则调用失败
`runtimeUrl`	前端连接的后端地址	路径	`/api/copilotkit`	`runtimeUrl="/api/copilotkit"`	写错则前端连不上
`basePath`	后端路由前缀	路径	`/api/copilotkit`	见 5.2	前后端对不上则 404

七、启动、后台常驻与开机自启

7.1 前台启动开发服务器

npm run dev

Next.js 默认 http://localhost:3000 ，右上角出现 CopilotSidebar。

7.2 生产构建与常驻

npm run build
npm run start

systemd 示例：

[Unit]
Description=My Copilot App
After=network.target

[Service]
Type=simple
User=ubuntu
WorkingDirectory=/home/ubuntu/my-app
EnvironmentFile=/home/ubuntu/my-app/.env.local
ExecStart=/usr/bin/npm run start
Restart=on-failure

[Install]
WantedBy=multi-user.target

7.3 开机自启

sudo systemctl daemon-reload && sudo systemctl enable --now copilotapp

7.4 修改端口

Next.js 用 -p 指定：npm run start -- -p 8080，访问 http://localhost:8080 验证。

八、功能实操教程

第 1 步：npx copilotkit@latest create 脚手架一个新工程。第 2 步：进入工程，npm install，把 OPENAI_API_KEY 写进 .env.local。第 3 步：npm run dev，浏览器打开 3000，看到右上角 Copilot 侧边栏。第 4 步：在侧边栏问一句话，观察 BuiltInAgent 流式回答。第 5 步：按官方文档加一个 frontend tool，让智能体在你的页面上点按钮 / 改状态。第 6 步：把 BuiltInAgent 换成你已有的 LangGraph / CrewAI agent，验证同一套 UI 复用。

九、全套报错故障排查

报错：npx copilotkit@latest create 卡住。原因：npm 源慢。解决：npm config set registry https://registry.npmmirror.com 后重试。
报错：前端聊天一直转圈，Network 里 /api/copilotkit 404。原因：路由文件位置不对或 basePath 不一致。解决：确认文件在 app/api/copilotkit/[[...slug]]/route.ts；basePath 与 runtimeUrl 一致。
报错：401 Unauthorized。原因：.env.local 没写 OPENAI_API_KEY，或 dev server 没重启。解决：补 Key 后 Ctrl+C 重启 npm run dev。
报错：@copilotkit/runtime/v2 导入失败。原因：装的是旧版本。解决：npm install @copilotkit/runtime@latest @copilotkit/react-core@latest。
报错：生成式 UI 不渲染。原因：组件没在 CopilotKit 注册。解决：按官方 Generative UI 文档注册自定义组件。

十、升级、回滚与卸载

升级：npm install @copilotkit/react-core@latest @copilotkit/runtime@latest。
回滚：npm install @copilotkit/react-core@<旧版本> @copilotkit/runtime@<旧版本>。
卸载：删 node_modules 与工程目录；从你的 app/page.tsx 移除 <CopilotKitProvider>。

十二、进阶：共享状态、人机协同与 Slack/Teams 多渠道

共享状态让 Agent 改 UI：CopilotKit 的 Shared State 是核心——你把 React 状态暴露给 Agent，用户说"把表格按金额排序"，Agent 直接调 setState，前端实时刷新，不需要页面跳转。官方文档有完整示例。

人机协同（HITL）：涉及删除、付款、发邮件这种危险动作，用 human-in-the-loop 让 Agent 暂停，弹出确认框等人点"同意/拒绝"，再继续执行。这是把 CopilotKit 从"聊天玩具"变成"生产工具"的关键。

前端工具：把"打开设置页""导出 CSV""发送 Slack 通知"注册成 frontend tool，Agent 在需要时直接调用你写好的 React 函数，比让它真的去点浏览器按钮安全得多。

一次编写多渠道：官方 Channels 功能让你写一套 JSX，同时渲染成 React 网页、Slack Block Kit、Microsoft Teams Adaptive Cards。同一份智能体，网页里是侧边栏，Slack 里是机器人，Teams 里是卡片。

部署：Next.js 应用 Vercel 一键部署；自托管时 npm run build && npm run start 起 3000 端口，前面套 Nginx + HTTPS，务必把 OPENAI_API_KEY 放在服务端环境变量里，不要打进前端 bundle。

十一、商用许可与合规风险提示

CopilotKit 核心开源采用 MIT License（README 徽章明确），商用友好。

注意：

CopilotKit Intelligence 是商业产品：跨会话记忆、持续学习、Soar 等企业能力是付费云服务，OSS 版不含。
模型费用：框架免费，OpenAI 等模型调用按 token 计费。
AG-UI 协议：开源协议，但若你要做兼容实现，参考 ag-ui-protocol 仓库规范。

参考链接

官方 README：https://github.com/CopilotKit/CopilotKit
快速接入：https://docs.copilotkit.ai/quickstart
生成式 UI：https://docs.copilotkit.ai/concepts/generative-ui-overview
人机协同：https://docs.copilotkit.ai/human-in-the-loop