Repository navigation
Installation
Installing CogitoAgent on Your System
在您的系统上安装 CogitoAgent
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+) | — |
There are two ways to install CogitoAgent: from source (recommended for development and customization) or via Docker (recommended for server deployment).
有两种方式可以安装 CogitoAgent:从源码安装(推荐用于开发和自定义)或通过 Docker 安装(推荐用于服务器部署)。
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-agentInstall the required npm packages.
安装所需的 npm 包。
npm installNote for users in China: If
npm installfails 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
Copy the example environment file and edit it with your configuration.
复制示例环境文件并根据您的配置进行编辑。
cp .env.example .envOpen .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-4oRun the type checker to verify the code is ready.
运行类型检查以验证代码是否就绪。
npm run typecheckIf no errors are reported, the installation is successful.
如果没有报错,则安装成功。
Docker deployment is recommended for server environments and production use.
Docker 部署推荐用于服务器环境和生产环境。
# Build from source
docker build -t cogito-agent:latest .
# Or use docker-compose (recommended)
docker-compose up -dCreate 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-4odocker-compose up -dVerify the container is running:
验证容器是否正在运行:
docker-compose psWhen you run CogitoAgent for the first time, the Setup Wizard will guide you through the configuration process.
当您首次运行 CogitoAgent 时,配置向导将引导您完成配置过程。
| 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、视觉等 |
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——适合服务器或无头环境 |
To verify CogitoAgent is working correctly:
要验证 CogitoAgent 是否正常工作:
-
Launch the application using one of the commands above
-
Enter a simple command like
/statusto check the system status -
Try a tool call like
[TOOL] ls(".") [/TOOL]to list files -
Check the WebSocket connection (port 9527) is established for Electron modes
-
启动应用程序,使用上述命令之一
-
输入简单命令,如
/status检查系统状态 -
尝试工具调用,如
[TOOL] ls(".") [/TOOL]列出文件 -
检查 WebSocket 连接(端口 9527)在 Electron 模式下是否已建立
After successful installation, proceed to:
安装成功后,请继续阅读:
-
Quick Start — Learn the basics of interacting with CogitoAgent
-
Configuration — Explore all configuration options in detail
-
Architecture Overview — Understand how CogitoAgent works
-
快速上手 — 学习与 CogitoAgent 交互的基础知识
-
配置说明 — 详细了解所有配置选项
-
架构设计 — 了解 CogitoAgent 的工作原理
Previous: Home →
Next: Quick Start →
上一篇: 首页 →
下一篇: 快速上手 →