Skip to content
Snow leopard edited this page Jul 16, 2026 · 1 revision

Installation

Installing CogitoAgent on Your System

在您的系统上安装 CogitoAgent


System Requirements | 系统要求

Before installing CogitoAgent, ensure your system meets the following requirements.

在安装 CogitoAgent 之前,请确保您的系统满足以下要求。

Requirement Minimum Recommended
Node.js 22.12 or higher Latest LTS version
npm 9.x or higher Latest version
Python 3.x (optional, for Python code execution) 3.10+
RAM 2GB 4GB+
Disk Space 500MB 1GB+
OS Windows 10/11, macOS 11+, or Linux (Ubuntu 20.04+) —
要求 最低配置 推荐配置
Node.js 22.12 或更高版本 最新 LTS 版本
npm 9.x 或更高版本 最新版本
Python 3.x(可选,用于 Python 代码执行) 3.10+
内存 2GB 4GB+
磁盘空间 500MB 1GB+
操作系统 Windows 10/11、macOS 11+ 或 Linux(Ubuntu 20.04+) —

Installation Methods | 安装方式

There are two ways to install CogitoAgent: from source (recommended for development and customization) or via Docker (recommended for server deployment).

有两种方式可以安装 CogitoAgent:从源码安装(推荐用于开发和自定义)或通过 Docker 安装(推荐用于服务器部署)。


Method 1: Installing from Source | 方式一:从源码安装

Step 1: Clone the Repository | 第一步:克隆仓库

Clone the CogitoAgent repository from GitHub or Gitee.

从 GitHub 或 Gitee 克隆 CogitoAgent 仓库。

# GitHub (international users)
git clone https://github.com/SnowLeopard-io/CogitoAgent.git

# Gitee (China users, faster)
git clone https://gitee.com/cnt-code/cogito-agent.git

cd cogito-agent

Step 2: Install Dependencies | 第二步:安装依赖

Install the required npm packages.

安装所需的 npm 包。

npm install

Note for users in China: If npm install fails to download the Electron binary, set the Electron mirror before running the command:

国内用户注意:如果 npm install 下载 Electron 失败,请在运行命令前设置 Electron 镜像源:

# Windows (PowerShell)
$env:ELECTRON_MIRROR = "https://npmmirror.com/mirrors/electron/"

# macOS / Linux
export ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/"

# Then run installation
npm install

Step 3: Configure Environment | 第三步:配置环境

Copy the example environment file and edit it with your configuration.

复制示例环境文件并根据您的配置进行编辑。

cp .env.example .env

Open .env and fill in at least the following required fields:

打开 .env 并至少填写以下必填字段:

# Required: Your LLM API key
COGITO_API_KEY=your-api-key-here

# Required: API base URL (OpenAI-compatible)
COGITO_API_BASE_URL=https://api.openai.com/v1

# Required: Model name
COGITO_MODEL=gpt-4o

Step 4: Verify Installation | 第四步:验证安装

Run the type checker to verify the code is ready.

运行类型检查以验证代码是否就绪。

npm run typecheck

If no errors are reported, the installation is successful.

如果没有报错,则安装成功。


Method 2: Installing via Docker | 方式二:通过 Docker 安装

Docker deployment is recommended for server environments and production use.

Docker 部署推荐用于服务器环境和生产环境。

Step 1: Pull or Build the Image | 第一步:拉取或构建镜像

# Build from source
docker build -t cogito-agent:latest .

# Or use docker-compose (recommended)
docker-compose up -d

Step 2: Configure Environment Variables | 第二步:配置环境变量

Create a .env file in the project root with your configuration:

在项目根目录创建 .env 文件并填入配置:

COGITO_API_KEY=your-api-key-here
COGITO_API_BASE_URL=https://api.openai.com/v1
COGITO_MODEL=gpt-4o

Step 3: Start the Container | 第三步:启动容器

docker-compose up -d

Verify the container is running:

验证容器是否正在运行:

docker-compose ps

First-Time Configuration | 首次配置

When you run CogitoAgent for the first time, the Setup Wizard will guide you through the configuration process.

当您首次运行 CogitoAgent 时,配置向导将引导您完成配置过程。

Configuration Steps | 配置步骤

Step Setting Description
1 API Base URL The API endpoint for your LLM provider (e.g., https://api.openai.com/v1)
2 API Key Your API authentication key
3 Model Name The model to use (e.g., gpt-4o, claude-3-sonnet, DeepSeek-V4-Flash)
4 Workspace The directory CogitoAgent can access and operate in
5 Persona (Optional) Choose a preset persona for the agent's behavior
6 Advanced (Optional) Configure thinking interval, email, OCR, vision, etc.
步骤 设置项 说明
1 API Base URL 您的 LLM 提供商的 API 端点(例如 https://api.openai.com/v1)
2 API Key 您的 API 认证密钥
3 模型名称 要使用的模型(例如 gpt-4o、claude-3-sonnet、DeepSeek-V4-Flash)
4 工作区 CogitoAgent 可以访问和操作的目录
5 人设 (可选)为 Agent 的行为选择预设角色
6 高级 (可选)配置思考间隔、邮件、OCR、视觉等

Launch Modes | 启动模式

After configuration, you can launch CogitoAgent in one of the following modes:

配置完成后,您可以通过以下模式之一启动 CogitoAgent:

Command Mode Description
npm run electron:desktop Desktop Mode Electron overlay window with a floating character — lightweight and always accessible
npm run electron:dashboard Dashboard Mode Full-featured dashboard with session management, tool visualization, and monitoring
npm run cli CLI Mode Terminal-only, no Electron — ideal for servers or headless environments
命令 模式 说明
npm run electron:desktop 桌面模式 Electron 悬浮窗口,带有浮动角色——轻量且随时可访问
npm run electron:dashboard 仪表盘模式 全功能仪表盘,包含会话管理、工具可视化和监控
npm run cli CLI 模式 纯终端模式,无 Electron——适合服务器或无头环境

Verification | 验证安装

To verify CogitoAgent is working correctly:

要验证 CogitoAgent 是否正常工作:

  1. Launch the application using one of the commands above

  2. Enter a simple command like /status to check the system status

  3. Try a tool call like [TOOL] ls(".") [/TOOL] to list files

  4. Check the WebSocket connection (port 9527) is established for Electron modes

  5. 启动应用程序,使用上述命令之一

  6. 输入简单命令,如 /status 检查系统状态

  7. 尝试工具调用,如 [TOOL] ls(".") [/TOOL] 列出文件

  8. 检查 WebSocket 连接(端口 9527)在 Electron 模式下是否已建立


Next Steps | 下一步

After successful installation, proceed to:

安装成功后,请继续阅读:


Previous: Home →

Next: Quick Start →

上一篇: 首页 →

下一篇: 快速上手 →

Clone this wiki locally