Apexo

开源的通用编程智能体(General-Purpose Coding Agent),同时支持终端(TUI)、浏览器(Web)与桌面端(Desktop)。

项目主页 (Website) | English | 简体中文

--- ## Apexo 是什么? Apexo 是一个**开源的通用编程智能体**,基于统一的本地智能体运行时,同时提供终端界面(TUI)、Web 界面和 Electron 桌面应用。 Apexo 并非绑定单一模型厂商的简单外壳,而是拥有深度演进的自研智能体架构——包括持久化会话引擎、自主目标执行(`/goal`)、多会话工作流(`/workflow`)、后台任务与子智能体编排(`/tasks`)、跨会话持久记忆(`/memory`)、原生命令沙盒(`/sandbox`)、生命周期钩子(`/hooks`)以及旁路快速提问(`/btw`)——并对各大主流模型生态提供一等公民级的原生支持: - **Google Gemini 与 Antigravity 深度支持:** 支持直接复用本机 Antigravity CLI(`agy`)的 Google 登录态(无需重复授权),也支持通过 `GOOGLE_GENERATIVE_AI_API_KEY` 直接接入 Gemini 系列模型;完整支持思考摘要(Reasoning Summary)、多模态附件与长上下文编程。详见 [Antigravity 接入说明](docs/antigravity.md)。 - **xAI Grok 与 Grok Build 工作流体验:** 支持使用 xAI 账号(SuperGrok 或 X Premium)通过 OAuth 设备码流程免密登录,或使用 `XAI_API_KEY`;原生支持 `grok-4.7`、`grok-4.6`、`grok-4.20`、`grok-build-0.1` 等模型与完整工具链。 - **通用多提供商与 OpenAI 兼容生态:** 原生支持 OpenAI、Anthropic(Claude)、MiniMax、DeepSeek、Qwen 以及任意自建/第三方 OpenAI 兼容服务(vLLM、Ollama、LM Studio 等),自动提取 `` 推理标签并支持增量流式输出与工具调用。 - **纯本地运行,无中间商订阅,无广告:** 没有托管模型网关、强制账号后台、会话上传或推销内容。所有能力均在本地运行,直接连接你所配置的模型提供商。 - **一套本地服务,三端一致体验:** 终端、Web 与桌面端共享同一个本地服务端、实时事件流和同一份持久化会话历史。 - **Grove 主题:** TUI、Web 与桌面端的默认暖黑绿配色主题,同时保留全部经典与自定义主题支持。 ### 登录与鉴权设计 Apexo 对 **Google Antigravity(`agy`)** 与 **xAI Grok** 提供**本地 OAuth / 原生 CLI 登录态复用**,同时对所有主流模型(Google Gemini、xAI、OpenAI、Anthropic、MiniMax 及任意 OpenAI 兼容接口)提供 API Key 与自定义端点直连支持。所有鉴权凭据均保存在本机,请求直达对应模型服务商。

Apexo 终端界面

Apexo Web 界面

## 核心能力 - **自主目标(`/goal`):** 设定目标与验证标准,智能体将自动规划并持续迭代,直至验证通过、主动暂停、受阻或预算耗尽。 - **多会话工作流(`/workflow`):** 在独立的子会话中并行推进多步骤工作流,主会话保持随时交互。 - **后台任务与子智能体(`/tasks`):** 集中管理后台命令、定时循环任务(`/loop`)、子智能体(Subagents)与协调器会话。 - **持久记忆系统(`/memory`、`/remember`、`/flush`、`/dream`):** 跨会话审阅、沉淀与整理项目级和用户级持久记忆。 - **原生命令沙盒(`/sandbox`):** 基于操作系统原生机制(macOS `seatbelt`、Linux `bubblewrap`)限制命令的文件写入与网络访问(支持 `workspace` 与 `read-only` 模式)。 - **生命周期钩子(`/hooks`):** 查看会话钩子快照,并提供仓库级显式信任授权管理。 - **旁路提问(`/btw`):** 在不打断当前主线任务、不污染主上下文的前提下,随时弹窗进行旁路问答。 ## 安装 ```bash npm install -g apexo-code apexo --version ``` CLI 独立压缩包和 Desktop 安装包均可在 [GitHub Releases](https://github.com/cluster1900/apexo-code/releases) 下载,不要求使用 npm。 - 使用 npm 需要 Node.js 22 或更新版本;不需要另装 Bun 或 Rust。固定版本可执行 `npm install -g apexo-code@1.0.0`。 - 直接下载 CLI 时,Apple Silicon 选择 `darwin-arm64`,Intel Mac 选择 `darwin-x64`;普通 Linux 选择 `linux-x64` 或 `linux-arm64`,Alpine 选择带 `musl` 的版本;Windows 选择 `windows-x64` 或 `windows-arm64`。 - x64 CPU 不支持 AVX2 时选择带 `baseline` 的版本。解压后将 `apexo` 和 `apexo-workflow-script` 放在同一目录(Windows 文件名带 `.exe`),并把该目录加入 PATH。 - Desktop 提供 macOS Apple Silicon 的 DMG/ZIP、Linux x64 的 AppImage/DEB/RPM,以及 Windows x64 的 EXE 安装程序。 - 首次打开可能需要通过系统的安全确认:当前 macOS 包使用临时签名且未公证,Windows 包没有发布者证书。请核对发布来源,并使用同一 Release 的 `SHA256SUMS` 验证下载文件。 完整步骤见[详细安装指南](docs/installation.md),包括无需 npm 的安装命令、Windows PowerShell 操作、PATH 配置、校验、更新和卸载。 ### 从源码构建 构建前需要安装 [Bun](https://bun.sh) 1.4.4(仓库固定为 `bun@1.4.4`)和 git。 ```bash git clone https://github.com/cluster1900/apexo-code.git apexo && cd apexo bun install # 为当前机器构建单个原生二进制(内嵌 Web UI) bun run --cwd packages/apexo build --single # 产物位于 packages/apexo/dist/apexo--/bin/apexo mkdir -p ~/.local/bin install -m755 packages/apexo/dist/apexo-*/bin/apexo ~/.local/bin/apexo install -m755 packages/apexo/dist/apexo-*/bin/apexo-workflow-script ~/.local/bin/apexo-workflow-script export PATH="$HOME/.local/bin:$PATH" apexo --version ``` 推送 `vX.Y.Z` 标签会触发 `.github/workflows/release.yml`,构建所有平台并把压缩包附加到 [GitHub Releases](https://github.com/cluster1900/apexo-code/releases)。发布之后,也可以用安装脚本获取 (`--version X.Y.Z` 指定版本): ```bash curl -fsSL https://raw.githubusercontent.com/cluster1900/apexo-code/main/install | bash ``` 不构建、直接从源码运行: ```bash bun dev # 等同于 bun run --cwd packages/apexo src/index.ts bun dev --help ``` ## 使用 ```bash apexo # 在当前目录启动终端界面(TUI) apexo auth login # 登录:支持 Google Antigravity、xAI Grok(OAuth)或配置 API key apexo auth list # 查看已配置的凭据 apexo models # 列出所有已配置提供商的可用模型 apexo run "解释一下这个仓库" # 一次性、非交互运行 apexo web # 启动本地服务并打开 Web 界面 apexo serve # 无界面服务(供桌面端、编辑器、脚本使用) apexo acp # 作为 ACP 智能体运行,供 Zed 等编辑器接入 ``` 在 TUI 与桌面端输入框中:`/connect` 打开提供商连接对话框,`/models` 切换模型,`/themes` 切换主题,`ctrl+p`(macOS 上为 `cmd+k` / `cmd+p`)打开命令面板;以 `!` 开头的输入会作为 shell 命令执行。 ### 提供商支持 | 提供商 | 连接方式 | 环境变量 | | ----------------------------------- | --------------------------------------------------------------------------------- | ------------------------------ | | **Google Gemini** | API key(支持 Google AI Studio 等) | `GOOGLE_GENERATIVE_AI_API_KEY` | | **Antigravity(Google / Gemini)** | 选择 Antigravity,直接复用本机 `agy` 登录态;未登录时通过 `agy` 完成一次 Google 授权 | — | | **xAI Grok** | `apexo auth login` -> xAI -> SuperGrok Subscription(设备码 OAuth),或 API key | `XAI_API_KEY` | | **OpenAI** | API key | `OPENAI_API_KEY` | | **Anthropic(Claude)** | API key | `ANTHROPIC_API_KEY` | | **自定义 / OpenAI 兼容服务** | 在 `apexo.jsonc` 中配置 `baseURL` 与 `apiKey`(如 MiniMax、DeepSeek、Ollama、vLLM)| 自定义 `{env:...}` | ### 桌面应用 Electron 桌面应用位于 `packages/desktop`: ```bash bun run --cwd packages/desktop dev # 开发模式 bun run --cwd packages/desktop build # 生产构建(打包使用 electron-builder) ``` 桌面应用没有自动更新;如需更新,请重新构建(或安装更新的发布版本)。 ## 配置 Apexo 读取 JSON/JSONC 配置文件: | 项目 | 位置 | | ------------------ | ---------------------------------------------------------------- | | 全局配置 | `~/.config/apexo/apexo.jsonc`(也可用 `apexo.json`) | | 数据 / 状态 / 缓存 | `~/.local/share/apexo`、`~/.local/state/apexo`、`~/.cache/apexo` | | 项目配置 | 项目中的 `apexo.json` / `apexo.jsonc`(向上查找到 git 根目录) | | 项目目录 | `.apexo/`(agents、commands、plugins、themes、tools) | | 环境变量 | `APEXO_*`(如 `APEXO_CONFIG`、`APEXO_CONFIG_CONTENT`) | `apexo.json` 示例: ```jsonc { "$schema": "https://raw.githubusercontent.com/cluster1900/apexo-code/main/schemas/config.json", "model": "google/gemini-2.5-pro", "theme": "grove", } ``` ### 自定义 OpenAI 兼容提供商(如 MiniMax / DeepSeek / Ollama) 你可以在 `~/.config/apexo/apexo.jsonc` 或项目根目录的 `apexo.jsonc` 中接入任意自建或第三方 OpenAI 兼容端点(例如 MiniMax、DeepSeek、Qwen、vLLM、Ollama、LM Studio 等): ```jsonc { "$schema": "https://raw.githubusercontent.com/cluster1900/apexo-code/main/schemas/config.json", "model": "custom/MiniMax-M2.7", "provider": { "custom": { "npm": "@ai-sdk/openai-compatible", "name": "Custom OpenAI-Compatible", "options": { "baseURL": "https://api.minimax.cn/v1", "apiKey": "{env:CUSTOM_API_KEY}", }, "models": { "MiniMax-M2.7": { "name": "MiniMax M2.7", }, }, }, }, } ``` 配置完成后,可运行 `apexo models` 验证自定义提供商与模型是否已注册成功。 编辑器补全用的 JSON Schema 位于 [`schemas/`](schemas):`config.json`(`apexo.json`)、`tui.json`、 `theme.json`(TUI 主题)和 `desktop-theme.json`(应用主题)。可用 `bun script/schemas.ts` 重新生成。 ## 主题 - **TUI:** 默认主题为 `grove`。可用 `/themes` 切换,或在 `tui.json`(`~/.config/apexo/tui.json`) 中设置 `"theme"`。自定义主题放在 `.apexo/themes/*.json` 或 `~/.config/apexo/themes/`。 - **Web / 桌面应用:** 在 设置 -> 外观 中默认使用 Grove,原有主题显示为 “Classic”。 ## 开发 ```bash bun install bun turbo typecheck --concurrency=2 (cd packages/core && bun test) (cd packages/apexo && bun test) (cd packages/tui && bun test) ``` 工作区包使用 `@apexo/*` 作用域,CLI 与服务端位于 `packages/apexo`。 ## 反馈 问题和建议请提交到 [github.com/cluster1900/apexo-code/issues](https://github.com/cluster1900/apexo-code/issues)。 ## 许可证 MIT,详见 [LICENSE](LICENSE)。