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

Configuration

Configuring CogitoAgent for Your Environment

为您的环境配置 CogitoAgent


CogitoAgent can be configured through two methods: a config.json file and environment variables (.env). Environment variables take priority over the configuration file, allowing you to override specific settings without modifying the file.

CogitoAgent 可以通过两种方式进行配置:config.json 文件和环境变量(.env)。环境变量的优先级高于配置文件,允许您在不修改文件的情况下覆盖特定设置。


Configuration Priority | 配置优先级

CogitoAgent loads configuration in the following order (later sources override earlier ones):

CogitoAgent 按以下顺序加载配置(后面的源会覆盖前面的):

Default Values → config.json → Environment Variables (.env)
默认值 → config.json → 环境变量 (.env)

This means you can use config.json for shared settings and .env for sensitive information like API keys.

这意味着您可以使用 config.json 来存放共享设置,使用 .env 来存放 API 密钥等敏感信息。


Quick Start Configuration | 快速开始配置

At minimum, you need to configure the following three settings to use CogitoAgent:

至少需要配置以下三项设置才能使用 CogitoAgent:

1. API Key | API 密钥

# In .env file
COGITO_API_KEY=your-api-key-here
// In config.json
{
  "api": {
    "apiKey": "your-api-key-here"
  }
}

2. API Base URL | API 基础地址

COGITO_API_BASE_URL=https://api.openai.com/v1
{
  "api": {
    "baseURL": "https://api.openai.com/v1"
  }
}

Common API base URLs:

Provider Base URL
OpenAI https://api.openai.com/v1
Moark https://api.moark.com/v1
DeepSeek https://api.deepseek.com/v1
OpenRouter https://openrouter.ai/api/v1
Anthropic https://api.anthropic.com/v1

常用 API 基础地址:

提供商 Base URL
OpenAI https://api.openai.com/v1
Moark https://api.moark.com/v1
DeepSeek https://api.deepseek.com/v1
OpenRouter https://openrouter.ai/api/v1
Anthropic https://api.anthropic.com/v1

3. Model Name | 模型名称

COGITO_MODEL=gpt-4o
{
  "api": {
    "model": "gpt-4o"
  }
}

Full Configuration Reference | 完整配置参考

config.json | 配置文件

{
  "api": {
    "provider": "openai",
    "baseURL": "https://api.openai.com/v1",
    "model": "gpt-4o"
  },
  "chat": {
    "maxTokens": 131072,
    "temperature": 0.7,
    "topP": 0.7,
    "topK": 50,
    "frequencyPenalty": 1,
    "thinkingInterval": 3000
  },
  "search": {
    "enabled": true,
    "recencyFilter": "",
    "siteFilter": ""
  },
  "workspace": "/path/to/your/workspace",
  "database": {
    "path": "./data/example.db"
  },
  "email": {
    "smtpHost": "smtp.example.com",
    "smtpPort": 587,
    "user": "user@example.com",
    "password": "",
    "from": "user@example.com"
  },
  "ocr": {
    "apiKey": "",
    "baseURL": "https://dashscope.aliyuncs.com/compatible-mode/v1",
    "model": "Qwen2.5-VL-32B-Instruct",
    "provider": "qwen-vl"
  },
  "vision": {
    "apiKey": "",
    "baseURL": "",
    "model": "Qwen2.5-VL-32B-Instruct"
  },
  "code": {
    "maxExecutionTime": 30000,
    "maxOutputSize": 100000
  },
  "security": {
    "confirmDangerous": true,
    "sandboxMode": true
  },
  "persona": "Assistant",
  "mode": "desktop",
  "tools": {
    "enabledCategories": ["file", "web", "code", "git"]
  }
}

Environment Variables (.env) | 环境变量

Create a .env file in the project root. Here is a complete reference:

在项目根目录创建 .env 文件。以下是完整参考:

# ============================================
# API Configuration (Required)
# API 配置(必需)
# ============================================

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

# ============================================
# Chat & Thinking Configuration
# 聊天与思考配置
# ============================================

COGITO_THINKING_INTERVAL=3000

# ============================================
# Mode Configuration
# 模式配置
# ============================================

COGITO_MODE=desktop

# ============================================
# Database Configuration
# 数据库配置
# ============================================

COGITO_DATABASE_PATH=./data/example.db

# ============================================
# Email Configuration (Optional)
# 邮件配置(可选)
# ============================================

COGITO_EMAIL_HOST=smtp.example.com
COGITO_EMAIL_PORT=587
COGITO_EMAIL_USER=user@example.com
COGITO_EMAIL_PASSWORD=your-password
COGITO_EMAIL_FROM=user@example.com

# ============================================
# OCR Configuration (Optional)
# OCR 配置(可选)
# ============================================

COGITO_OCR_API_KEY=your-ocr-api-key
COGITO_OCR_API_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
COGITO_OCR_MODEL=Qwen2.5-VL-32B-Instruct
COGITO_OCR_PROVIDER=qwen-vl

# ============================================
# Vision Configuration (Optional)
# 视觉分析配置(可选)
# ============================================

COGITO_VISION_API_KEY=
COGITO_VISION_API_BASE_URL=
COGITO_VISION_MODEL=Qwen2.5-VL-32B-Instruct

# ============================================
# Code Execution Configuration
# 代码执行配置
# ============================================

COGITO_CODE_TIMEOUT=30000
COGITO_CODE_MAX_OUTPUT=100000

# ============================================
# Security Configuration
# 安全配置
# ============================================

COGITO_CONFIRM_DANGEROUS=true
COGITO_SANDBOX_MODE=true

# ============================================
# Workspace & Persona
# 工作区与人设
# ============================================

COGITO_WORKSPACE=./workspace
COGITO_PERSONA=Assistant

# ============================================
# Multi-Model API Keys (Optional)
# 多模型 API 密钥(可选)
# ============================================

COGITO_OPENAI_API_KEY=
COGITO_MOARK_API_KEY=
COGITO_ANTHROPIC_API_KEY=
COGITO_GOOGLE_API_KEY=

Configuration Details | 配置详解

API Configuration | API 配置

Field Environment Variable Description 说明
api.apiKey COGITO_API_KEY Your API authentication key 您的 API 认证密钥
api.baseURL COGITO_API_BASE_URL API endpoint URL API 端点地址
api.provider COGITO_API_PROVIDER Provider name: openai, moark, etc. 提供商名称
api.model COGITO_MODEL Model name to use 要使用的模型名称

Thinking Interval | 思考间隔

Field Environment Variable Default 默认值
chat.thinkingInterval COGITO_THINKING_INTERVAL 3000 ms 3000 毫秒

The thinking interval controls how often the agent automatically triggers a thinking cycle. Lower values make the agent more responsive but consume more tokens.

思考间隔控制 Agent 自动触发思考周期的频率。较低的值使 Agent 响应更快,但会消耗更多 Token。

Mode | 模式

Value Description 说明
desktop Desktop pet mode with floating character 桌面宠物模式,带浮动角色
dashboard Full dashboard window 全屏仪表盘窗口

Workspace | 工作区

The workspace is the directory where CogitoAgent can read, write, and execute files. Set this to a safe directory that the agent should have access to.

工作区是 CogitoAgent 可以读取、写入和执行文件的目录。请将其设置为 Agent 应有权访问的安全目录。

COGITO_WORKSPACE=/home/user/projects

Persona | 人设

Personas define the agent's personality. See the Quick Start for a complete list.

人设定义了 Agent 的性格。完整列表请参阅快速上手。

COGITO_PERSONA=Programmer

Tool Categories | 工具分类

You can enable or disable entire tool categories using tools.enabledCategories:

您可以使用 tools.enabledCategories 启用或禁用整个工具分类:

{
  "tools": {
    "enabledCategories": ["file", "web", "code", "git"]
  }
}

All available categories:

所有可用分类:

Category Tools 工具数
file ls, read, copy, mkdir, create 5
web search, browse, fetchPage 3
system listApps, openApp, closeApp 3
browser initBrowser, clickElement, fillField, etc. 12
code executeCode, runJavaScript, runPython, etc. 5
git gitInit, gitClone, gitCommit, gitPush, etc. 21
task createTask, getTasks, completeTask, etc. 9
memory addMemory, searchMemory, deleteMemory, etc. 9
data readCSV, writeJSON, queryData, analyzeData, etc. 9
db executeSQL, query, insert, update, etc. 11
email sendEmail, checkEmailConfig, etc. 6
monitor getCPUInfo, getMemoryInfo, monitorSystem, etc. 9
scheduler addScheduleTask, getScheduleTasks, etc. 8
ocr ocr, ocrBatch 2
vision vision, visionFromUrl 2
office createPpt, createWord, createExcel, readExcel 4
cluster spawnAgent, delegateTask, getClusterStatus, etc. 10
wechat loginWechat, sendWechatMessage, etc. 6
gis convertCoord, calcDistance, readGeoJSON, etc. 11
bio dnaComplement, translate, parseFASTA, etc. 15
med bmi, egfr, childPugh, convertUnit, etc. 17
chem molWeight, elementInfo, phFromH, etc. 9
finance compoundInterest, npv, irr, loanPayment, etc. 12
math describe, correlation, linearRegression, etc. 11

Security | 安全

Field Environment Variable Default Description
security.confirmDangerous COGITO_CONFIRM_DANGEROUS true Require confirmation for dangerous operations
security.sandboxMode COGITO_SANDBOX_MODE true Enable code execution sandbox
字段 环境变量 默认值 说明
security.confirmDangerous COGITO_CONFIRM_DANGEROUS true 危险操作需要确认
security.sandboxMode COGITO_SANDBOX_MODE true 启用代码执行沙箱

Advanced: Context Compression | 高级:上下文压缩

CogitoAgent automatically compresses conversation history when it grows too large:

当对话历史增长过大时,CogitoAgent 会自动压缩:

Parameter Value Description
compressTurns 150 Trigger compression after this many turns
keepRecentTurns 10 Keep this many recent turns intact
maxTokenEstimate 100,000 Token threshold for compression
参数 值 说明
compressTurns 150 超过此轮数后触发压缩
keepRecentTurns 10 保留最近此数量的完整对话
maxTokenEstimate 100,000 压缩的 Token 阈值

These values are hardcoded in session.ts and can be modified there if needed.

这些值在 session.ts 中硬编码,如有需要可在该文件中修改。


Next Steps | 下一步


Previous: Quick Start →

Next: Architecture Overview →

上一篇: 快速上手 →

下一篇: 架构设计 →

Clone this wiki locally