Aperant（Auto Claude）桌面应用使用与配置指南：从快速上手到源码运行-开发者社区

人工智能
AI Agent
自主智能体
代码智能体
桌面应用
前端
开发工具

【免费下载链接】Aperant

Autonomous multi-session AI coding

项目地址：https://gitcode.com/gh_mirrors/au/Aperant

Aperant（原 Auto Claude）是一款基于 Electron 的自主多智能体（multi-agent）编码桌面应用，用户描述目标后，AI 智能体会自动完成规划、编码与质量验证。本文以官方使用文档 guides/CLI-USAGE.md 为核心骨架，结合仓库源码与配置，完整讲解快速上手流程、从源码运行的三种命令模式，以及通过设置界面完成账户连接、Provider 配置、记忆系统与集成服务配置的全部细节。

快速上手：五分钟跑通第一个任务

根据 guides/CLI-USAGE.md 的 Getting Started 章节，Aperant 的完整使用链路非常简单，全部功能均通过 Electron 桌面 UI 操作，无需手动管理命令行进程。官方推荐的步骤为：

下载安装包：从项目的 Releases 页面下载对应平台的发行版本并安装。当前仓库维护两条版本线：稳定版（2.7.6）与 Beta 版（2.8.0-beta.x），覆盖 Windows（.exe）、macOS（Apple Silicon 与 Intel 的.dmg）、Linux（AppImage、Deb、Flatpak）三种平台，安装包均附带 SHA256 校验和与 VirusTotal 扫描结果，可在 README.md 的 Download 章节查看。
启动应用：安装并打开桌面应用。
打开项目：在应用内选择并打开一个 git 仓库文件夹作为工作项目。这是硬性前提——README 的 Requirements 明确要求"项目必须已初始化为 git 仓库"，因为所有构建工作都发生在隔离的 git worktree 中，主分支不会被污染。
连接 Claude：按照应用内置的 OAuth 设置引导完成账户授权。
创建任务：描述你想构建的目标，智能体会自动规划、编码、验证并交付。

上手前需要满足的运行时前置条件（见 README.md Requirements 与 CONTRIBUTING.md Prerequisites）：

依赖	说明
Claude Pro/Max 订阅	OAuth 连接所需的账户订阅
Claude Code CLI	`npm install -g @anthropic-ai/claude-code`，全局安装
Git 仓库	项目目录必须`git init`过
Node.js 24+ / npm 10+	仅源码运行时需要，用于构建 Electron 应用

从源码运行：install、dev 与 start

对于想要测试未发布功能或参与开发的用户，guides/CLI-USAGE.md 给出了从源码运行的三种命令模式，均在仓库根目录执行：

# 安装全部依赖 npm run install:all # 开发模式（热重载） npm run dev # 生产构建 + 运行 npm start

这三条命令在根目录 package.json 中有明确的脚本定义，理解其底层行为有助于排查问题：

install:all实际执行cd apps/desktop && npm install，即安装桌面应用子项目（唯一的 Electron 应用，位于 apps/desktop/）的全部依赖。安装过程会触发postinstall脚本 apps/desktop/scripts/postinstall.cjs，自动处理原生模块（如 node-pty 终端库）的预构建二进制下载与重建，这也是 Windows 上通常无需手动安装 Visual Studio Build Tools 的原因。
dev转发为cd apps/desktop && npm run dev，即electron-vite dev，提供 Vite 驱动的热模块替换（HMR），主进程与渲染进程代码改动即时生效，是日常开发推荐模式。
start等价于cd apps/desktop && npm run build && npm run start：先用electron-vite build构建产物到out/，再以electron .启动打包后的应用，模拟接近生产的行为。

值得注意的扩展命令（根目录 package.json 与 apps/desktop/package.json）：开发调试可用npm run dev:debug（开启详细日志，供 AI 自验证的 Electron MCP 调试）与npm run dev:mcp（暴露--remote-debugging-port=9222，允许 QA 智能体通过 Chrome DevTools 协议驱动应用）。应用数据（spec、任务记录等）默认写入项目下的.auto-claude/目录（gitignored），可从 CLAUDE.md 的 Running the Application 章节确认。

配置：一切皆在 Settings UI

guides/CLI-USAGE.md 明确指出：所有配置均通过应用的 Settings 界面完成，无需手工编辑配置文件。以下是文档列举的五大配置维度及仓库源码层面的佐证。

1. 连接 Claude 账户：OAuth 或 API Key

应用支持注册多个 Claude 账户并随时切换，连接方式分两种：

OAuth：通过 Claude 订阅账户授权，走应用内置的 OAuth 引导流程；
API Key：直接填写 Anthropic API Key 等凭据。

从源码看，凭证解析由 apps/desktop/src/main/ai/auth/resolver.ts 及其测试 apps/desktop/src/main/ai/auth/tests/resolver.test.ts 实现。测试用例按阶段（Stage）展示了凭据解析的优先级链：

Profile OAuth Token：优先使用已注册 Profile 的有效 OAuth token，且 token 过期时会自动刷新（ensureValidToken返回wasRefreshed标记）；
Profile API Key：无 OAuth token 时回退到 Profile 配置的 API Key（测试中对应sk-from-settings/sk-settings-key等取值）；
Settings 全局 Key：继续回退到设置中的全局 Anthropic API Key；
Default Credentials：对于 Ollama 等本地 Provider，返回空 API Key 即可。

底层凭据管理在 apps/desktop/src/main/claude-profile/ 模块中：credential-utils.ts使用操作系统凭据存储（macOS Keychain / Windows Credential Manager），token-refresh.ts负责 OAuth token 生命周期与自动刷新，usage-monitor.ts跟踪各 Profile 的用量与限流——当某个账户触达速率限制时，应用会自动切换（swap）到可用账户。

2. 多 Provider Profile：Anthropic、OpenAI、Google 等

Settings 界面支持配置多种 Provider 的 Profile。仓库的 Provider 注册表与工厂位于 apps/desktop/src/main/ai/providers/，根据 CLAUDE.md 的说明，其createProviderRegistry()至少支持：Anthropic、OpenAI、Google、Bedrock（AWS）、Azure、Mistral、Groq、xAI、Ollama。这一清单与 apps/desktop/package.json 的依赖一一对应（@ai-sdk/anthropic、@ai-sdk/openai、@ai-sdk/google、@ai-sdk/amazon-bedrock、@ai-sdk/azure、@ai-sdk/mistral、@ai-sdk/groq、@ai-sdk/xai、@ai-sdk/openai-compatible，另有@openrouter/ai-sdk-provider）。

这意味着除了官方 Anthropic 端点，你还可以接入任何 Anthropic 兼容端点（例如 z.ai 的 GLM 模型），实现"订阅账户 + API Profile"的灵活组合。每个 Provider 的适配层会处理 thinking token 归一化与提示缓存（prompt caching）等细节差异，对用户透明。

3. 启用 Graphiti 记忆系统

Settings 中可开启 Graphiti 记忆系统，让智能体跨会话保留洞察。从源码结构看，这套知识图谱记忆由两部分组成：

主进程侧的集成与注入逻辑：apps/desktop/src/main/ai/context/graphiti-integration.ts 负责将检索到的记忆注入智能体上下文；
可选的 Graphiti 内存服务位于 apps/desktop/src/main/ai/memory/（含db.ts、embedding-service.ts、graph/、retrieval/、observer/等子模块），通过@ai-sdk/mcp的 MCP 客户端连接，配置入口在应用的 onboarding/settings 界面。

4. 设置默认模型与思考预算（Thinking Budgets）

Settings 可设置默认模型与思考预算。对应实现位于 apps/desktop/src/main/ai/config/agent-configs.ts：维护着一个包含 25+ 种智能体类型的AGENT_CONFIGS注册表，提供按阶段（phase）感知的模型解析与思考预算控制。也就是说，不同角色（规划者、编码者、QA 审查者）可以分配不同的模型与 token 预算，从而在成本与质量之间取得平衡。

5. 配置 Linear / GitHub / GitLab 集成

Settings 中可配置团队协作平台的集成：

GitHub：IPC 处理器位于 apps/desktop/src/main/ipc-handlers/github/，支持导入 Issue、AI 调查、PR 审查与创建、OAuth、自动修复等；
GitLab：对应 apps/desktop/src/main/ipc-handlers/gitlab/ 模块，功能与 GitHub 侧对齐（Merge Request 审查等）；
Linear：由 apps/desktop/src/main/ipc-handlers/linear-handlers.ts 支撑，可将任务与 Linear 双向同步，用于团队进度跟踪。

附：常用命令速查

README.md 与 apps/desktop/README.md 汇总了根目录与桌面子项目的完整命令表，这里摘取与"使用 + 从源码运行"最相关的部分：

命令	作用
`npm run install:all`	从根目录安装全部依赖（等价`cd apps/desktop && npm install`）
`npm run dev`	开发模式，热重载
`npm start`	生产构建后运行
`npm run build`	仅执行生产构建
`npm run package`	打包当前平台安装包
`npm run package:win`/`package:mac`/`package:linux`/`package:flatpak`	分别打包 Windows / macOS / Linux / Flatpak 格式
`npm run lint`/`lint:fix`	Biome 静态检查 / 自动修复
`npm test`	Vitest 前端单元测试
`npm run test:e2e`	Playwright 端到端测试（需先`npm run build`）
`npm run typecheck`	TypeScript 严格模式类型检查

Linux 用户构建与安装 AppImage / Debian / Flatpak 的详细步骤，参见 guides/linux.md；完整的开发环境搭建（含 Node.js 24 安装、CMake 前置、Windows 构建工具说明）参见 CONTRIBUTING.md 与 CLAUDE.md。

总结

Aperant 的使用体验高度集中在桌面 UI：下载安装 → 打开 git 项目 → OAuth 连接 Claude → 创建任务即完成闭环；从源码运行时仅需install:all/dev/start三条命令；而所有扩展能力（多 Provider、Graphiti 记忆、模型与思考预算、团队集成）都在 Settings 界面内配置。无论你是终端用户还是开发者，这份指南都能让你在数分钟内完成环境搭建并让自主智能体开始工作。