# cdex-gateway

**Repository Path**: nn200433/cdex-gateway

## Basic Information

- **Project Name**: cdex-gateway
- **Description**: 纯ai项目，自己耍，不负责维护
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2026-03-16
- **Last Updated**: 2026-03-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Codex Plus v3

`codex-plus-v3` 是一个面向本地开发场景的 Codex 网关项目，提供：

- 基于 Fastify 的后端网关服务
- 基于 Vue 3 + Vite 的前端控制台
- 面向工作区项目的实例创建、会话管理、文件预览能力
- Windows 下将前后端整合为单个 `exe` 的打包方案

当前主程序位于 `codex-gateway/` 目录，根目录用于承载仓库说明和打包入口脚本。

## 项目结构

```text
codex-plus-v3/
├─ codex-gateway/              # 主应用目录
│  ├─ src/                     # 后端源码
│  ├─ frontend/                # 前端源码
│  ├─ scripts/                 # 内部构建/打包脚本
│  ├─ config.yaml              # 主配置文件
│  ├─ .env                     # 环境变量文件
│  └─ package.json             # 后端依赖与脚本
├─ README.md                   # 根目录说明文档
├─ build-exe.ps1               # Windows 一键打包脚本
└─ build-exe.cmd               # Windows 双击启动包装器
```

## 核心能力

### 1. Web 控制台

启动后可通过浏览器访问网关页面，默认地址：

```text
http://127.0.0.1:3000
```

前端提供桌面端和移动端两套入口：

- `/`：桌面控制台
- `/m`：移动端页面

### 2. 工作区项目管理

后端会扫描配置中的 `workspace.path` 目录，将其下可识别项目展示到控制台。

目前可识别的项目类型：

- Node.js 项目
- Java 项目
- Git 仓库

同时支持从界面新建项目目录。

### 3. Codex 实例与线程管理

系统支持：

- 基于某个项目路径创建 Codex 实例
- 为实例开启新线程
- 获取线程列表
- 恢复历史线程
- 查看线程消息历史
- 查看实例日志与文件变更

### 4. 文件树与文件预览

前端支持浏览工作区项目的文件树，并读取常见文本文件内容，例如：

- `ts` / `tsx` / `js` / `vue`
- `json` / `yaml` / `md`
- `java` / `sql` / `ps1`

系统默认会跳过部分大目录和构建目录，例如：

- `node_modules`
- `.git`
- `dist`
- `build`
- `target`

### 5. 飞书机器人接入

后端内置飞书机器人接入逻辑，可按配置启用。启用后可通过飞书消息控制实例和会话。

如果你暂时不需要飞书，只需保持：

```yaml
feishu:
  enabled: false
```

## 环境要求

### 基础要求

- Node.js `22.0.0` 或更高版本
- npm
- Windows 10/11（如需打包 `exe`）

### 运行依赖

项目本身不会安装 Codex CLI，需要你本地已经具备可执行命令，并在 `config.yaml` 中正确配置。

当前默认配置示例：

```yaml
codex:
  command: "D:\\ProgormData\\nodejs\\codex.cmd"
```

你需要根据本机实际安装位置修改为正确路径。

## 配置说明

主配置文件位于：

```text
codex-gateway/config.yaml
```

默认内容中最关键的几项如下：

```yaml
server:
  host: "127.0.0.1"
  port: 3000

auth:
  password: "${AUTH_PASSWORD:-admin123}"

workspace:
  path: "${WORKSPACE_PATH:-./workspace}"

codex:
  maxInstances: 5
  idleTimeout: 1800000
  command: "D:\\ProgormData\\nodejs\\codex.cmd"
  defaultModel: "gpt-5.4"
  approvalPolicy: "never"
  sandboxMode: "danger-full-access"
```

### 配置项解释

- `server.host`：服务监听地址
- `server.port`：服务端口
- `auth.password`：控制台登录密码
- `workspace.path`：工作区根目录
- `codex.maxInstances`：最大实例数
- `codex.idleTimeout`：空闲自动回收时间，单位毫秒
- `codex.command`：Codex CLI 命令路径
- `codex.defaultModel`：默认模型
- `codex.approvalPolicy`：审批策略
- `codex.sandboxMode`：沙箱模式

### 环境变量

后端启动时会读取：

```text
codex-gateway/.env
```

配置文件支持 `${VAR}` 和 `${VAR:-default}` 占位语法，因此可以把敏感值放进 `.env` 中，例如：

```env
AUTH_PASSWORD=your-password
WORKSPACE_PATH=./workspace
FEISHU_ENABLED=false
```

## 开发运行

### 1. 安装后端依赖

在仓库根目录执行：

```powershell
cd codex-gateway
npm install
```

### 2. 安装前端依赖

```powershell
cd codex-gateway/frontend
npm install
```

### 3. 启动后端开发服务

```powershell
cd codex-gateway
npm run dev
```

### 4. 启动前端开发服务

新开一个终端：

```powershell
cd codex-gateway/frontend
npm run dev
```

### 5. 访问开发页面

前端 Vite 默认会输出本地开发地址，后端默认监听：

```text
http://127.0.0.1:3000
```

如果前后端联调时需要确认接口可用性，可以先访问：

```text
http://127.0.0.1:3000/health
```

返回：

```json
{ "status": "ok" }
```

## 生产构建

### 构建前端

```powershell
cd codex-gateway
npm run build:frontend
```

### 构建后端

```powershell
cd codex-gateway
npm run build
```

### 启动构建后的后端

```powershell
cd codex-gateway
npm start
```

## EXE 打包

项目已经内置基于 Node SEA 的 Windows 打包逻辑，会将：

- 后端入口打包并注入到一个 `exe`
- 前端构建产物复制到发布目录 `public/`
- `config.yaml` 一起复制到发布目录
- 自动生成生产环境 `.env`
- 自动创建 `workspace/` 目录

### 一键打包方式

在仓库根目录执行：

```powershell
.\build-exe.ps1
```

或者双击：

```text
build-exe.cmd
```

### 打包输出目录

打包完成后产物位于：

```text
codex-gateway/release/win-x64/
```

目录结构大致如下：

```text
release/win-x64/
├─ codex-gateway.exe
├─ config.yaml
├─ .env
├─ public/
└─ workspace/
```

### 运行 EXE

进入发布目录后直接执行：

```powershell
.\codex-gateway.exe
```

程序会以发布目录作为运行基准目录，因此以下文件都应与 `exe` 保持同级或子目录关系：

- `config.yaml`
- `.env`
- `public/`
- `workspace/`

## 常用命令速查

### 后端

```powershell
cd codex-gateway
npm run dev
npm run build
npm start
npm run build:frontend
npm run pack:win
```

### 前端

```powershell
cd codex-gateway/frontend
npm run dev
npm run build
npm run preview
```

## 常见问题

### 1. 页面能打开，但无法创建实例

优先检查：

- `codex-gateway/config.yaml` 中的 `codex.command` 是否为真实可执行路径
- 当前系统是否已正确安装并可直接运行 Codex CLI
- `workspace.path` 中是否存在可识别项目

### 2. 登录失败

检查：

- `auth.password`
- `.env` 中是否覆盖了 `AUTH_PASSWORD`

### 3. 打包失败

优先检查：

- Node 版本是否为 `22+`
- 后端与前端依赖是否完整安装
- 当前 Node 是否包含 `--experimental-sea-config` 支持

### 4. EXE 启动后找不到页面资源

确认发布目录下存在：

- `public/index.html`
- `config.yaml`

不要只复制 `exe` 单文件运行，需保留整个发布目录。

## 开发建议

- 修改后端配置逻辑时，优先验证源码运行和打包运行两种模式
- 修改前端资源路径时，确认打包后 `public/` 静态资源仍可被 Fastify 正常托管
- 新增配置项时，同时更新 `config.yaml` 和本说明文档

## 许可证

当前仓库未声明独立许可证文件，如需对外分发，请先由项目维护者明确许可证策略。