本文档详细介绍 OpenAkita 桌面客户端的完整配置流程，包括快速配置和完整配置两种模式。

• 1. 开始之前
• 2. 选择配置模式
• 3. 快速配置
  • 3.1 填写配置
  • 3.2 自动配置
  • 3.3 完成
• 4. 完整配置
  • 4.1 工作区
  • 4.2 Python 环境
  • 4.3 安装
  • 4.4 LLM 端点
  • 4.5 IM 通道
  • 4.6 工具与技能
  • 4.7 Agent 与系统
  • 4.8 完成
• 5. 快速配置默认值参考
• 附录：配置项速查表

安装完成后，双击打开 OpenAkita 桌面客户端。首次启动时会自动进入配置向导。

首次进入配置向导，你将看到模式选择页面，提供两种配置方式：

提示：你随时可以通过侧边栏的「切换配置模式」回到这个页面，重新选择配置方式。

快速配置适合希望快速上手的用户。系统会自动完成以下工作：

• 创建默认工作区
• 安装内置 Python 3.11
• 创建虚拟环境并安装所有依赖
• 写入推荐默认配置

你只需要完成 LLM 端点配置（必填）和 IM 通道配置（可选）。

点击「快速配置」后进入配置填写页面，包含两个区域：

你至少需要添加 1 个 LLM 端点 才能开始使用。点击「+ 添加端点」按钮打开端点配置对话框：

高级选项（点击展开）：

• API Type：openai（默认）或 anthropic
• Key 环境变量名：API Key 在 .env 中存储的变量名
• 优先级：数值越小优先级越高（默认 0）

添加成功后，端点会出现在列表中：

点击「IM 通道」区域的展开按钮，可以配置即时通讯接入。不配置也可以正常使用 OpenAkita（通过桌面聊天窗口交互）。

支持的 IM 通道：

各 IM 通道的详细接入教程请参考 IM 通道接入文档。

填写完所有必要信息后，点击页面底部的 「开始配置」 按钮。

如果尚未添加任何 LLM 端点，按钮会处于禁用状态，并提示「请先添加至少 1 个 LLM 端点」。

点击「开始配置」后，系统将自动执行以下步骤：

注意：此过程中请保持网络畅通。如果安装失败，可以点击「返回模式选择」切换到完整配置模式手动排查。

自动配置完成后，你将看到配置摘要页面：

页面显示以下信息：

• 工作区：工作区名称和路径
• LLM 端点：已配置的端点数量
• IM 通道：已启用的通道列表（如有）

你可以选择：

• 「启动服务」：立即启动 OpenAkita 后端服务并跳转到状态面板
• 「跳转状态面板」：不启动服务，仅查看状态面板

恭喜！快速配置已完成，你现在可以开始使用 OpenAkita 了。

完整配置提供对每个环节的精细控制，适合需要自定义环境、调整参数的高级用户。

工作区是 OpenAkita 的配置隔离单元。每个工作区独立维护以下文件：

• .env — 环境变量配置
• data/llm_endpoints.json — LLM 端点列表
• identity/SOUL.md — 角色灵魂文件

操作说明：

提示：首次使用建议直接创建一个「默认」工作区即可。多工作区适合需要区分生产/测试/不同客户环境的场景。

OpenAkita 需要 Python 3.11+ 运行环境。你有两种选择：

点击 「安装内置 Python」 按钮，系统将自动下载并安装 Python 3.11 嵌入版到 ~/.openakita/runtime/ 目录。

• 完全隔离，不影响系统已有 Python
• 由 OpenAkita 自动管理

如果你已经安装了 Python 3.11+，点击 「检测系统 Python」，系统会扫描可用的 Python 安装：

• 自动检测 PATH 中的 python3、python 命令
• 显示版本号和可用性状态
• 从下拉框选择你希望使用的 Python

注意：请确保选择的 Python 版本 ≥ 3.11，低版本可能导致兼容性问题。

在此步骤中完成虚拟环境创建和 OpenAkita 包安装。

安装过程中会显示实时日志和进度条：

LLM 端点是 OpenAkita 调用大语言模型的入口。你可以配置多个端点，系统会根据优先级和可用性自动选择。

点击 「+ 添加端点」 打开配置对话框：

基本配置：

高级配置（点击展开）：

国内服务商：

国际服务商：

OpenAkita 支持配置多个端点，提供自动故障转移能力：

• 优先级调度：优先使用 Priority 值最小的端点
• 自动降级：主端点不可用时自动切换到备用端点
• 健康检查：后台定期检测端点可用性
• 冷却机制：连续失败的端点会被临时冷却，避免反复重试

建议：至少配置 2 个端点（不同服务商），以确保高可用性。

编译器端点用于代码编译、格式化等辅助任务。如果不配置，系统会使用主端点。

IM 通道让你可以通过即时通讯工具与 OpenAkita 对话。所有通道均为可选配置。

接入方式：Long Polling（默认），无需公网 IP。

接入方式：自建应用，无需公网 IP。在飞书开放平台创建应用并获取凭证。

接入方式：智能机器人，需要公网 IP。回调地址格式：http://your-domain:9880/callback

接入方式：企业内部应用，无需公网 IP。在钉钉开放平台创建应用。

接入方式：通过 QQ 官方开放平台 API v2（WebSocket Gateway + REST），支持群聊、单聊、频道消息。需要在 q.qq.com 注册并创建机器人。

接入方式：OneBot v11 协议，可对接任何兼容 OneBot 的实现端（如 NapCat、Lagrange 等）。

此步骤配置 OpenAkita 可以使用的工具和技能扩展。

MCP（Model Context Protocol）允许 OpenAkita 通过标准化协议调用外部工具。

桌面自动化让 OpenAkita 可以操作你的电脑桌面（截图、点击、输入等）。

高级选项：

Skills 是可插拔的技能扩展。包括：

• 系统技能：内置技能（只读）
• 外部技能：用户安装的第三方技能，可单独启用/禁用

此步骤配置 Agent 行为、角色人格、记忆系统和调度器等核心参数。

OpenAkita 内置多种预设角色人格：

活人感模式让 Agent 更像一个有温度的伙伴，会主动问候和关心用户。

点击「高级设置」展开更多选项：

日志配置：

记忆与向量化（遗留功能，可选）：

注意：向量记忆功能依赖 sentence-transformers 和 chromadb，这些组件已不再作为默认依赖安装。如需使用向量记忆，请手动安装：pip install sentence-transformers chromadb。未安装时系统将使用基于数据库的普通记忆方案。

会话管理：

主动消息高级：

配置全部填写完毕后进入完成页面。

完成页面提供：

• 配置文件检查：显示工作区目录路径和生成的配置文件列表
• 启动服务：点击按钮启动 OpenAkita 后端服务
• 卸载 / 清理（可选）：卸载 openakita 包或删除运行环境

点击「启动服务」后，系统会自动跳转到状态面板，你可以在那里监控服务运行状态。

以下是快速配置模式自动写入的所有默认值：

各个 Agent 的显示名称由桌面端「Agents」菜单中的 Agent Profile 管理，不再通过环境变量配置。

以下配置仅在手动安装 sentence-transformers 和 chromadb 后生效。

所有配置项均通过工作区的 .env 文件管理。文件位于：

~/.openakita/workspaces/{workspace_id}/.env

LLM 端点列表单独存放在：

~/.openakita/workspaces/{workspace_id}/data/llm_endpoints.json

提示：你可以直接编辑这些文件，但建议通过桌面客户端的配置界面修改，以避免格式错误。修改 .env 后需要重启服务生效，或在客户端使用「应用并重启」按钮。

文档版本：v1.10.7 | 最后更新：2026-02-12