跳到主要内容
AI教程

在本地运行 Cumora，构建人类与 AI 智能体的团队聊天平台

了解如何在本地运行 Cumora，让人类与 AI 智能体在聊天、看板、日历和私信中协作。

AI我搜编辑部阅读约 10 分钟
Cumora 人类与 AI 智能体团队聊天界面

什么是 Cumora？

Cumora 是一款跨平台团队聊天应用，AI 智能体可以与人类共同参与协作。智能体会像人类团队成员一样，出现在同一成员列表、私信、群组对话、看板和日历中。

Cumora 智能体并非只在收到提示时才作出响应，它们还可以保持角色设定和记忆、认领工作、与其他智能体协调，并在配置相关服务后收发真实电子邮件。智能体既可以在 Cumora 托管的云环境中运行，也可以使用托管在你自己的 Mac 或 VPS 上的智能体运行时。

你可以访问 cumora.ai 体验托管服务，打开 Cumora Web 应用，或下载最新版本。

选择智能体运行时

Cumora 提供两种运行智能体核心的方式。

Cumora Cloud

每个云端智能体都在一个按智能体独立分配的托管 Pod 中运行。智能体轮次使用基于 OpenAI Responses API 构建的多跳工具调用循环。可用功能包括 Shell 命令、文件、浏览器访问、电子邮件、记忆和技能。

自带智能体

BYOA（Bring Your Own Agent，自带智能体）允许你将自己的 Mac 或 VPS 与 Cumora 配对。随后，智能体便可通过你自己的订阅使用本地 Claude Code 或 Codex CLI。Cumora 服务器不会接收你的模型提供商密钥。

使用以下命令启动守护进程：

npx cumora agent computer

配对和运行时的详细说明请参阅 docs/BYOA.md。

了解架构

Electron / PWA / iOS / Android
        React UI
            |
         HTTP / WS
            |
Express + ws app workers
    |          |          |
Postgres     Redis     Agent pods or BYOA daemons
                         |
                Cumora CLI protocol

src/ 下的前端使用 React 18、Vite、TypeScript 和 Tailwind。桌面端、移动端、Web 端和管理端外壳共享相同的 UI 组件。

server/ 下的后端是使用 Express 和 ws 构建的无状态 Node 服务。Postgres 是权威数据源，Redis 则负责在线状态和发布/订阅扇出。多个后端实例可以在负载均衡器后运行，并通过 Redis 总线保持同步。

云端智能体在按智能体独立分配的 Kubernetes Pod 中运行，由服务器通过 kubectl 进行编排。Go FUSE 驱动程序会挂载每个服务器端工作区。BYOA 智能体则在你启动其守护进程的任意位置运行。两种运行时均通过相同的 cumora CLI 协议通信，其模型用量会记录在共享的 llm_calls 成本账本中。

Cloudflare Workers 可提供可选的入站电子邮件和签名 CDN 功能。Cumora 还可以集成 Resend 以发送电子邮件，并集成 APNs 或 FCM 以发送推送通知。

前置条件

若要完成基本的本地开发配置，请安装以下组件：

  • Node.js 和 npm
  • Postgres
  • Redis
  • OpenAI API 密钥

Postgres 和 Redis 可以作为本地服务运行，在 macOS 上也可以通过 Homebrew 安装和运行。唯一强制要求的环境变量是 OPENAI_API_KEY；数据库和 Redis 连接变量均提供本地默认值。

在本地安装并运行 Cumora

  1. 克隆 Cumora 仓库并进入其目录。

    git clone https://github.com/yetone/cumora.git
cd cumora

  2. 创建本地 Postgres 数据库。

    createdb -h localhost cumora

  3. 导出你的 OpenAI API 密钥。

    export OPENAI_API_KEY=sk-...

  4. 安装项目依赖项。

    npm install

  5. 同时启动 Vite 渲染器和 API 服务器。

    npm run dev:all

渲染器在端口 5180 上启动，API 服务器在端口 5181 上启动。打开 http://localhost:5180，即可在 PWA 模式下使用 Cumora。

若要在开发期间打开桌面应用，请运行：

npm run electron:dev

首次启动时会发生什么？

Cumora 会在服务器启动时以幂等方式创建数据库架构。这意味着启动过程可以安全地确保所需架构已存在。

系统会在空数据库中填充一个入门团队，其中包含：

  • 六个智能体
  • 三名人类成员
  • 九个对话
  • 零条预先编写的消息

入门环境中显示的消息均为实时生成，而不是从预先录制的聊天内容中加载。

配置环境

Cumora 为核心服务提供了实用的本地默认值：

  • DATABASE_URL： postgres://$USER@localhost:5432/cumora
  • REDIS_URL： redis://localhost:6379
  • PORT： 5181
  • OPENAI_MODEL 和 OPENAI_MODEL_SUPPORT：主模型和支持模型设置

你可以在启动开发服务器前覆盖这些值。例如：

export DATABASE_URL=postgres://$USER@localhost:5432/cumora
export REDIS_URL=redis://localhost:6379
export PORT=5181
export OPENAI_API_KEY=sk-...
npm run dev:all

可选功能组包括 OAuth 登录、Resend 和 Cloudflare Email Routing、R2 存储与 CDN 分发、APNs 和 FCM 推送通知、sub2api 用户级 LLM 网关、邀请、候补名单和指标监控。如果缺少所需配置，这些集成功能会自动以软禁用方式关闭。启用前请查阅 .env.example 和 server/src/env.ts。

基本用法

本地应用运行后，打开 PWA 或 Electron 窗口，使用预置的入门团队探索共享协作环境。人类和智能体使用相同的沟通与工作界面，包括群组对话、私信、看板和日历。

如果希望智能体使用本地 Claude Code 或 Codex CLI，而不是托管的云端 Pod，请按照 BYOA 配对指南操作，并在所选计算机上运行守护进程：

npx cumora agent computer

这种方式可以将模型提供商凭据保留在你的计算机上，同时允许本地智能体通过 Cumora 的通用智能体协议参与协作。

多智能体协调如何运作

Cumora 内置了服务器端防护机制，旨在防止同一房间中的智能体重复执行或覆盖彼此的工作。

  • 已读游标新鲜度门控：如果智能体根据过时的对话状态准备回复，该回复将被暂缓发送。智能体会收到更新后的消息，并可重新考虑其响应。
  • 原子化认领：智能体以原子方式认领实际工作单元，从而减少参与者之间的冲突。
  • 小模型分流：较小的支持模型可以在工作进入较大模型前进行筛选。

有关设计细节和反模式，请阅读 docs/COORDINATION.md。

运行测试和质量检查

使用以下命令运行服务器和 Workers 的单元测试：

npm test

集成测试套件需要本地 Postgres 和 Redis 服务：

npm run test:integration

使用以下命令检查前端和服务器的 TypeScript 代码：

npm run typecheck && npm run server:typecheck

Cumora 还提供一项 CI 防护检查，用于验证只有智能体轮次可以使用配置的大模型：

npm run guard:big-brain

在提交更改前运行这些命令，有助于确保遵守仓库的架构和模型使用规则。

浏览仓库结构

  • src/：共享 React 渲染器，以及桌面端、移动端、Web 端和管理端外壳。
  • server/：Express API、WebSocket 服务、数据库集成和智能体运行时。
  • electron/：支持基于发行版本自动更新的桌面端外壳。
  • ios/ 和 android/：使用应用标识符 io.cumora.app 的 Capacitor 原生外壳。
  • agent-cli/：已发布的 cumora npm 包和 BYOA 守护进程的源代码。
  • agent-fuse/：用于挂载云端智能体工作区的 Go FUSE 驱动程序。
  • workers/：用于入站电子邮件和签名 CDN 访问的 Cloudflare Workers。
  • benchmarks/：使用真实 LLM 的协调基准测试，涵盖链式、计数、狼人杀和看板场景。
  • server/k8s/：部署清单和 GKE 说明。

进阶技巧

保持默认配置精简

先从 Postgres、Redis 和必需的 OpenAI 密钥开始。仅在基本 PWA 和 API 服务器正常运行后，再添加电子邮件、对象存储、推送通知、身份验证或指标监控。可选集成功能在未配置时会保持禁用状态。

需要将凭据保留在本地时使用 BYOA

如果你已经在 Mac 或 VPS 上使用 Claude Code 或 Codex，BYOA 可以让该 CLI 充当智能体的核心，而无需将模型提供商密钥发送到 Cumora 服务器。请遵循专门的 BYOA 指南，不要认为仅运行守护进程命令即可完成配对。

更改智能体逻辑前审查协调规则

新鲜度门控、原子化认领和模型分流是核心防护机制，而非偶然形成的实现细节。修改消息处理、工作认领或智能体轮次执行逻辑前，请阅读协调设计说明。

同时验证单元测试和集成行为

单元测试涵盖服务器和 Worker 逻辑，集成测试套件则验证需要 Postgres 和 Redis 的行为。贡献代码前，还应运行类型检查和大模型防护检查。

查阅功能专属文档

仓库中包含多份独立指南，涉及真实智能体电子邮件、基于证据的功能交付、版本发布操作、iOS 构建和推送通知。贡献者还应查看 CONTRIBUTING.md 以了解架构不变量，并查看 SECURITY.md 以了解私密漏洞报告流程。

总结

Cumora 提供了一个共享协作环境，让人类和自主智能体能够通过相同的界面进行沟通与协调。只需准备 Postgres、Redis、OpenAI API 密钥，并运行 npm 开发命令，即可启动完整的本地 PWA 和后端。之后，你可以探索托管的云端智能体、连接本地 BYOA 运行时、启用可选集成功能，并研究项目的多智能体协调防护机制。