# Codex Mate
**一站式本地 AI 编程智能体管理面板。统一管理 Codex、Claude Code、Gemini CLI、CodeBuddy Code、Pi、OpenCode、KiloCode 与 OpenClaw，支持 Provider 切换、会话管理与任务编排。纯本地优先，你的智能体控制中心。**
[项目文档]
[快速开始]
[English]
[](https://www.npmjs.com/package/codexmate)
[](https://github.com/SakuraByteCore/codexmate/actions/workflows/release.yml)
[](https://www.npmjs.com/package/codexmate)
[](#homebrew-安装macos--linux)
[](#快速开始)
[](https://nodejs.org/)
[](LICENSE)
[](https://github.com/SakuraByteCore/codexmate/stargazers)
[](https://github.com/SakuraByteCore/codexmate/issues)
---
> [!TIP]
> **本地优先**：所有配置和会话均存储在您的主目录中。无需遥测，无需云端账户。
> [!IMPORTANT]
> 本项目目前处于早期开发阶段。我们正在寻找开发者共同构建本地智能体生态！
## 什么是 Codex Mate?
你是否曾因管理多个本地 AI 智能体而感到疲惫？每个工具都有自己的配置格式、会话存储和 Skills 目录。
**Codex Mate** 提供了一个统一的控制平面，让混乱重归有序。这是一个本地优先的 CLI + Web UI，旨在无缝管理 [Codex](https://github.com/openai/codex)、[Claude Code](https://github.com/anthropic-ai/claude-code)、[OpenCode](https://opencode.ai/)、KiloCode 和 [OpenClaw](https://github.com/moeru-ai/openclaw)。
### 有什么独特之处？
不同于简单的封装，Codex Mate 充当了 **本地智能体桥接器**：
- **统一会话浏览器**：在一个地方检索、预览、筛选并导出 Codex、Claude Code、Gemini CLI、CodeBuddy Code 与 Pi 的本地会话。
- **OpenAI 兼容桥接**：通过归一化 Responses API，让 Codex 能够与任何支持 OpenAI 格式的 UI 配合使用；内建 Codex 转换会补齐并规范化 `User-Agent`、`Version`、`OpenAI-Beta`、`Originator` 等 Codex 指纹，对上游伪装为官方 Codex CLI 请求。
- **Claude Provider 桥接**：通过内建本地 Claude 兼容代理，让 Claude Code 接入 OpenAI Chat Completions 兼容 provider 与 Ollama。
- **OpenCode Provider 控制**：在 `~/.codexmate` 下维护 CodexMate 自有的 OpenCode 多 provider 存储，只将当前选中的 provider 投影到 OpenCode 原生配置，避免污染或误删用户已有配置。
- **Provider 健康清理**：探测本地 Codex 与 Claude provider 路由，在同一个弹窗里集中展示失败配置，并批量清理已选坏配置，不影响正常或受保护项。
- **Skills 市场**：本地优先的市场，支持在不同的智能体应用之间共享和导入 Skills。
- **提示词文件编辑器**：统一编辑全局和项目级 `CLAUDE.md` 与 `AGENTS.md`，支持项目路径自动检测，并提供通用预设池复用 prompt。
- **任务编排器**：支持带有依赖跟踪的复杂任务规划与执行。
---
## 当前进展
| 特性 | 状态 | 描述 |
| --- | --- | --- |
| **Provider 管理** | ✅ | 切换 Codex、Claude、OpenCode、KiloCode 和 OpenClaw 的 provider/model |
| **状态实时同步** | ✅ | 实时感知 Codex/Claude 的配置与运行状态变更 |
| **会话浏览器** | ✅ | 跨 Codex、Claude Code、Gemini CLI、CodeBuddy Code 与 Pi 的本地会话进行检索、预览、筛选与导出 |
| **Usage 统计** | ✅ | 可视化消息趋势与热门项目统计 |
| **本地 Skills 市场** | ✅ | 跨应用的智能体 Skills 导入与导出 |
| **任务队列** | ✅ | 基于 DAG 的任务执行与日志查看 |
| **OpenAI 桥接** | ✅ | 将 Codex Responses API 转换为标准 OpenAI 格式，并在内建转换中附加/规范化 Codex 指纹 |
| **Claude Provider 桥接** | ✅ | 通过内建 Claude 兼容代理，让 Claude Code 接入 OpenAI Chat Completions 兼容 provider 与 Ollama |
| **OpenCode Provider 存储** | ✅ | 在 `~/.codexmate` 中保留多个 OpenCode provider，只将当前选中的 provider 投影到 OpenCode 原生配置 |
| **Provider 健康检查** | ✅ | 探测本地 Codex/Claude provider 路由，标记失败配置，并安全批量移除已选坏配置 |
| **提示词模板** | ✅ | 支持变量的可复用提示词插件 |
| **提示词文件编辑器** | ✅ | 编辑全局和项目级 CLAUDE.md / AGENTS.md，支持自动检测、路径切换与通用预设池。应用预设只更新编辑器，需手动保存才会写入文件。 |
| **MCP 集成** | ✅ | 通过 MCP stdio 暴露本地工具与资源 |
| **自动更新** | ✅ | 通过 `codexmate update` 快速更新 CLI |
---
## 快速开始
### Homebrew 安装（macOS / Linux）
```bash
brew tap SakuraByteCore/codexmate
brew install codexmate
```
需要 [Node.js](https://nodejs.org/)（如未安装可执行 `brew install node`）。
### 通过 npm 安装
```bash
npm install -g codexmate
codexmate run
```
如果默认 Web UI 端口 `3737` 不可用，Codex Mate 会自动尝试后续端口（`3738`、`3739` ...）。如需固定端口，可以指定 `CODEXMATE_PORT`：
```bash
CODEXMATE_PORT=8080 codexmate run
```
Windows PowerShell：
```powershell
$env:CODEXMATE_PORT=8080; codexmate run
```
### 通过 curl 安装 (独立包)
```bash
curl -fsSL https://raw.githubusercontent.com/SakuraByteCore/codexmate/main/scripts/install.sh | bash
```
### 支持的智能体
- **Codex**: `npm install -g @openai/codex`
- **Claude Code**: `npm install -g @anthropic-ai/claude-code`
- **Gemini CLI**: `npm install -g @google/gemini-cli`
- **CodeBuddy**: `npm install -g @tencent-ai/codebuddy-code`
- **KiloCode**: `npm install -g @kilocode/cli`（`kilo` / `kilocode`）
- **OpenCode**: 参照 [OpenCode 官方文档](https://opencode.ai/) 安装
- **OpenClaw**: 参见 [OpenClaw 仓库](https://github.com/moeru-ai/openclaw)
- **Pi**: 会话从 `~/.pi/agent/sessions` 自动发现
---
## 架构总览
```mermaid
%%{ init: { 'flowchart': { 'curve': 'catmullRom' } } }%%
flowchart TD
User([用户])
CLI[CLI 命令]
WebUI[Web 界面]
MCP[MCP 服务]
subgraph Mate [Codex Mate 核心]
API[HTTP API]
Config[配置引擎]
Session[会话管理器]
Skills[Skills 市场]
Tasks[任务运行器]
end
subgraph Local [本地文件系统]
CodexDir[~/.codex]
ClaudeDir[~/.claude]
ClawDir[~/.openclaw]
OpenCodeDir[~/.config/opencode]
MateDir[~/.codexmate]
State[会话/Usage/回收站]
end
User --> CLI & WebUI & MCP
CLI & WebUI & MCP --> API
API --> Config & Session & Skills & Tasks
Config --> CodexDir & ClaudeDir & ClawDir & OpenCodeDir & MateDir
Session --> State
Skills --> Local
```
---
## 特别鸣谢
感谢所有贡献者对 Codex Mate 的辛勤付出 ❤️