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

FAQ

Frequently Asked Questions

常见问题解答


This page answers common questions about CogitoAgent installation, configuration, usage, and troubleshooting.

本页解答关于 CogitoAgent 安装、配置、使用和故障排除的常见问题。


Installation & Setup | 安装与设置


Q: What are the system requirements for CogitoAgent?

CogitoAgent 的系统要求是什么?

Node.js 22.12 or higher, npm 9.x or higher, and at least 2GB of RAM. Python 3.x is optional but recommended for Python code execution features.

Node.js 22.12 或更高版本、npm 9.x 或更高版本,以及至少 2GB 内存。Python 3.x 是可选的,但推荐用于 Python 代码执行功能。


Q: How do I fix Electron download failures during npm install?

如何解决 npm install 期间 Electron 下载失败的问题?

Set the Electron mirror before running npm install:

在运行 npm install 之前设置 Electron 镜像源:

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

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

# Then install
npm install

Q: Can I use CogitoAgent without Electron?

我可以不使用 Electron 运行 CogitoAgent 吗?

Yes. Use the CLI mode:

可以。使用 CLI 模式:

npm run cli

This runs CogitoAgent in a terminal-only mode, ideal for servers or headless environments.

这会在纯终端模式下运行 CogitoAgent,适合服务器或无头环境。


Q: How do I update CogitoAgent to the latest version?

如何将 CogitoAgent 更新到最新版本?

git pull
npm install

If you are using Docker:

如果您使用 Docker:

docker-compose pull
docker-compose up -d

Configuration | 配置


Q: Where does CogitoAgent store its configuration?

CogitoAgent 将配置存储在哪里?

Configuration is stored in two places:

配置存储在两个位置:

  • config.json — Shared configuration | 共享配置
  • .env — Environment variables (sensitive data) | 环境变量(敏感数据)

Environment variables take priority over config.json.

环境变量的优先级高于 config.json。


Q: How do I change the API model?

如何更改 API 模型?

Edit .env or config.json:

编辑 .env 或 config.json:

# .env
COGITO_MODEL=gpt-4o
// config.json
{
  "api": {
    "model": "gpt-4o"
  }
}

Q: How do I change the thinking interval?

如何更改思考间隔?

# .env
COGITO_THINKING_INTERVAL=3000  # milliseconds | 毫秒

Or in config.json:

或在 config.json 中:

{
  "chat": {
    "thinkingInterval": 3000
  }
}

Note: Minimum value is 1000ms (1 second).

注意:最小值为 1000ms(1 秒)。


Q: Can I disable dangerous operation confirmation?

我可以禁用危险操作确认吗?

Yes, but this is not recommended for production:

可以,但不建议在生产环境中这样做:

COGITO_CONFIRM_DANGEROUS=false

This will automatically execute operations like gitPush, executeCode, dropTable, etc., without user confirmation.

这将自动执行 gitPush、executeCode、dropTable 等操作,无需用户确认。


Q: How do I enable or disable specific tool categories?

如何启用或禁用特定的工具分类?

Use the tools.enabledCategories field in config.json:

在 config.json 中使用 tools.enabledCategories 字段:

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

See the Configuration page for a complete list of categories.

完整分类列表请参阅配置说明页面。


Usage | 使用


Q: What is the [TOOL] syntax?

[TOOL] 语法是什么?

[TOOL] is the syntax used to call tools in CogitoAgent:

[TOOL] 是在 CogitoAgent 中调用工具所使用的语法:

[TOOL] toolName("argument1", "argument2") [/TOOL]

Examples | 示例:

[TOOL] ls(".") [/TOOL]
[TOOL] read("README.md") [/TOOL]
[TOOL] search("AI news") [/TOOL]

Q: What is the [WAIT] tag and why is it important?

[WAIT] 标签是什么?为什么它很重要?

[WAIT] is a marker that tells the agent "I'm done speaking, wait for user input." It is the most important rule in CogitoAgent:

[WAIT] 是一个标记,告诉 Agent "我说完了,等待用户输入"。这是 CogitoAgent 中最重要的规则:

  • Always add [WAIT] when you have something to say to the user

  • Never add [WAIT] when you need to continue working (e.g., waiting for tool results)

  • 当你有话对用户说时,一定要加 [WAIT]

  • 当你需要继续工作时,绝对不要加 [WAIT](例如等待工具结果)

Golden Rule: When you write a message to the user, always end with [WAIT].

黄金法则:当你写了一段话给用户时,总是以 [WAIT] 结尾。


Q: How do I manage multiple sessions?

如何管理多个会话?

Command Description 说明
/sessions List all sessions 列出所有会话
/new Create a new session 创建新会话
/switch <id> Switch to a session 切换到指定会话
/delete <id> Delete a session 删除会话
/rename <name> Rename current session 重命名当前会话

Q: How do I switch between personas?

如何切换人设?

# List available personas | 列出可用人设
/personas

# Switch to a specific persona | 切换到指定人设
/persona Programmer
/persona Assistant
/persona Detective

Q: What is the WebSocket port and how do I change it?

WebSocket 端口是什么?如何更改?

The default WebSocket port is 9527. It can be changed in ws-server.ts:

默认 WebSocket 端口是 9527。可以在 ws-server.ts 中更改:

const WS_PORT = process.env.WS_PORT || 9527;

Or via environment variable:

或通过环境变量:

WS_PORT=9528 npm run electron

Troubleshooting | 故障排除


Q: CogitoAgent says "Unknown tool" when I try to use a tool.

当我尝试使用工具时,CogitoAgent 提示 "未知工具"。

This means the tool is not registered. Check that:

这表示工具未注册。检查:

  1. The tool is in registry.ts

  2. The tool is in the TOOL_REGISTRY object

  3. The tool name is spelled correctly in the [TOOL] syntax

  4. 工具是否在 registry.ts 中

  5. 工具是否在 TOOL_REGISTRY 对象中

  6. [TOOL] 语法中的工具名称拼写是否正确


Q: WebSocket connection fails (port 9527).

WebSocket 连接失败(端口 9527)。

The port might be occupied or blocked:

端口可能被占用或阻止:

# Check port usage | 检查端口占用
# Windows
netstat -ano | findstr :9527

# macOS / Linux
lsof -i :9527

# Kill the process | 结束进程
# Windows: taskkill /PID <pid> /F
# macOS/Linux: kill -9 <pid>

# Or kill by port | 或按端口结束
npx kill-port 9527

Q: The agent is not thinking or responding.

Agent 没有思考或响应。

Check the following:

检查以下内容:

  1. State: The agent should be in AWAITING_INPUT or THINKING state

  2. WebSocket: Check if the WebSocket connection is established

  3. API Key: Verify your API key is valid

  4. Network: Check your internet connection

  5. Logs: Check the terminal output for errors

  6. 状态:Agent 应处于 AWAITING_INPUT 或 THINKING 状态

  7. WebSocket:检查 WebSocket 连接是否已建立

  8. API Key:验证您的 API 密钥是否有效

  9. 网络:检查您的网络连接

  10. 日志:检查终端输出中的错误


Q: Tool execution is stuck or takes too long.

工具执行卡住或耗时过长。

Check the timeout settings:

检查超时设置:

COGITO_CODE_TIMEOUT=30000  # 30 seconds | 30 秒

If the tool is a browser automation task, ensure Playwright is properly installed:

如果是浏览器自动化任务,请确保 Playwright 已正确安装:

npx playwright install

Q: How do I reset CogitoAgent to factory settings?

如何将 CogitoAgent 重置为出厂设置?

To reset to factory settings:

要重置为出厂设置:

# Delete runtime data | 删除运行时数据
rm -rf data/

# Delete configuration | 删除配置
rm config.json .env

# Re-run setup | 重新运行设置
npm start

This will remove all sessions, memory, tasks, and configuration. You will need to run the setup wizard again.

这将删除所有会话、记忆、任务和配置。您需要重新运行设置向导。


Performance | 性能


Q: How much memory does CogitoAgent use?

CogitoAgent 使用多少内存?

  • Idle: ~200-400 MB
  • Active (thinking): ~400-800 MB
  • Heavy tool usage: ~800-1500 MB

Memory usage depends on the LLM provider, conversation length, and tool usage.

内存使用取决于 LLM 提供商、对话长度和工具使用情况。


Q: How can I reduce token usage?

如何减少 Token 使用?

  1. Increase thinking interval — COGITO_THINKING_INTERVAL=5000

  2. Use shorter conversation history — Use /clear or start new sessions

  3. Disable unused tools — Use tools.enabledCategories to limit available tools

  4. Use cheaper models — Switch to a more cost-effective model

  5. 增加思考间隔 — COGITO_THINKING_INTERVAL=5000

  6. 使用更短的对话历史 — 使用 /clear 或创建新会话

  7. 禁用未使用的工具 — 使用 tools.enabledCategories 限制可用工具

  8. 使用更便宜的模型 — 切换到更具成本效益的模型


Q: Does CogitoAgent support GPU acceleration?

CogitoAgent 是否支持 GPU 加速?

CogitoAgent runs on CPU. GPU acceleration is only relevant for the LLM API you are using (most cloud APIs use GPU inference on the server side). Local LLM inference via Ollama can leverage GPU if configured.

CogitoAgent 在 CPU 上运行。GPU 加速仅与您使用的 LLM API 相关(大多数云 API 在服务器端使用 GPU 推理)。通过 Ollama 的本地 LLM 推理在配置后可以利用 GPU。


Development | 开发


Q: How do I create a custom tool?

如何创建自定义工具?

See the Plugin System page for detailed instructions. In summary:

详细说明请参阅插件系统页面。简要来说:

  1. Create a plugin in plugins/my-plugin/index.js
  2. Export an array of tool definitions
  3. Restart CogitoAgent
  4. Use [TOOL] yourTool(args) [/TOOL]

Q: How do I create a custom persona?

如何创建自定义人设?

Create a directory in personas/ with your persona name, and add a persona.md file:

在 personas/ 中创建一个以人设名称命名的目录,并添加 persona.md 文件:

# Your Persona Name (Your-Persona-ID)

You are a ... (description)

## 性格特点
- Trait 1
- Trait 2

## 说话风格
- Style description
- Example phrases

## 行为模式
- Behavior 1
- Behavior 2

Then switch with /persona Your-Persona-ID.

然后使用 /persona Your-Persona-ID 切换。


Q: What testing framework does CogitoAgent use?

CogitoAgent 使用什么测试框架?

CogitoAgent uses Jest with ts-jest for unit and integration tests.

CogitoAgent 使用 Jest 配合 ts-jest 进行单元和集成测试。

# Run all tests | 运行所有测试
npm test

# Run end-to-end tests | 运行端到端测试
npm run test:e2e

# Run tests in watch mode | 在监听模式下运行测试
npm run test:e2e:watch

Q: How do I contribute to CogitoAgent?

如何为 CogitoAgent 做贡献?

  1. Fork the repository on GitHub

  2. Create a feature branch

  3. Write code following the project style

  4. Run tests to ensure everything passes

  5. Submit a Pull Request

  6. 在 GitHub 上 Fork 仓库

  7. 创建功能分支

  8. 按照项目风格编写代码

  9. 运行测试确保全部通过

  10. 提交 Pull Request


License | 许可证

CogitoAgent is licensed under the Apache License 2.0.

CogitoAgent 使用 Apache License 2.0 许可证。


Previous: Deployment →

Next: Development Guide → (optional)

上一篇: 部署指南 →

下一篇: 开发指南 → (可选)

Clone this wiki locally