# Codex Responses 协议转换代理

**Repository Path**: LLS312885991/codex-proxy

## Basic Information

- **Project Name**: Codex Responses 协议转换代理
- **Description**: OpenAI Responses API 到 Chat Completions API 协议转换服务，专为对接国产大模型设计，支持流式响应、工具调用、思考模式透传及可视化管理
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-05-29
- **Last Updated**: 2026-05-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# @roson_liu/codex-proxy

OpenAI Responses API 到 Chat Completions API 协议转换代理服务。专为对接国产大模型（DeepSeek、Qwen、GLM 等）设计，让 Codex CLI 等 Responses API 客户端能够通过国产 LLM 提供服务。

## 工作原理

```
Codex CLI                        国产 LLM
    │                                │
    │  POST /v1/responses            │
    │  (Responses API)               │
    └─────►  Codex Proxy  ──────────►│
            协议转换引擎              │
            Responses → Chat         │
            ◄────────────────────────┘
            Chat → Responses
```

服务端将 Codex 的 Responses API 请求转换为 Chat Completions 格式，转发给国产 LLM，再将响应转换回 Responses API 格式返回给 Codex。

## 安装

```bash
# 全局安装
npm install -g @roson_liu/codex-proxy

# 启动服务（默认端口 10204）
codex-proxy

# 指定端口
codex-proxy --port 10205

# 或从源码运行
git clone <your-repo-url>
cd codex-proxy
npm install
npm run dev
```

启动后：

- 管理面板：http://localhost:10204/admin
- 代理端点：http://localhost:10204/v1/responses
- 模型列表：http://localhost:10204/v1/models

## Codex CLI 配置

```bash
export OPENAI_BASE_URL=http://localhost:10204/v1
export OPENAI_API_KEY=any-non-empty-value
```

## 管理面板功能

### 渠道管理

配置上游 LLM 提供商：

| 字段 | 说明 |
|------|------|
| 渠道名称 | 自定义名称，用于路由匹配 |
| Base URL | 上游 API 地址（如 `https://api.deepseek.com`） |
| API Key | 上游 API 密钥 |
| 超时（秒） | 请求超时时间，默认 300s |
| 权重 | 多渠道负载均衡时的权重值 |
| 快捷匹配模型 | 该渠道可处理的模型名列表，用于按模型名自动路由 |

### 模型路由

四层优先级路由解析：

1. **显式路由表** — 指定模型别名 → 渠道 + 实际模型名
2. **渠道模型+权重分发** — 多个渠道声明同名模型时按权重随机选择
3. **默认路由** — 未匹配时使用默认渠道
4. **单渠道兜底** — 仅配置一个渠道时自动使用

### 其他

- **系统设置**：修改监听端口、日志级别
- **服务状态**：运行时长、请求统计、配置管理
- **请求日志**：按级别过滤，按请求分组展示，支持自动刷新
- **渠道连通测试**：一键测试渠道连通性

## 支持的供应商

| 供应商 | 渠道名包含 | 适配处理 |
|--------|-----------|----------|
| DeepSeek | `deepseek` | 思考模式（reasoning_content 多轮透传）、logprobs/logit_bias 字段移除 |
| 通义千问 (Qwen) | `qwen` / `tongyi` / `dashscope` | `output.choices` 格式适配、XML tool_call 提取 |
| 智谱 GLM | `zhipu` / `glm` / `bigmodel` | `do_sample` 参数设置、思考模式 |

## 协议转换说明

### 请求转换（Responses → Chat）

| Responses API | Chat Completions API |
|---------------|---------------------|
| `instructions` | 前缀 `system` 消息 |
| `input` 中 `input_text` / `input_image` | `user` / `assistant` 消息 |
| `input` 中 `reasoning` | 缓存文本，附加到下一个 `assistant` 消息的 `reasoning_content` |
| `input` 中 `function_call` | 合并为带 `tool_calls` 的 `assistant` 消息 |
| `input` 中 `function_call_output` | `tool` 角色消息 |
| `tools`（顶层 `name/description/parameters`） | `tools`（`function` 嵌套格式） |
| `max_output_tokens` | `max_tokens` |
| `reasoning.effort` | `reasoning_effort` |
| `developer` 角色 | 映射为 `system` 角色 |

### 响应转换（Chat → Responses）

| Chat Completions API | Responses API |
|---------------------|---------------|
| `reasoning_content` | `reasoning` output item（`summary_text`） |
| `content` | `message` output item（`output_text`） |
| `tool_calls` | `function_call` output items |

### 流式转换

流式场景下维护完整的 SSE 事件序列：

```
response.created
  → response.output_item.added (reasoning)
    → response.reasoning_summary_part.added
    → response.reasoning_summary_text.delta × N
    → response.reasoning_summary_part.done
    → response.output_item.done
  → response.output_item.added (message)
    → response.content_part.added
    → response.output_text.delta × N
    → response.content_part.done
    → response.output_item.done
  → response.output_item.added (function_call)
    → response.function_call_arguments.delta × N
    → response.function_call_arguments.done
    → response.output_item.done
→ response.completed
```

## 项目结构

```
package.json        — 包配置，npm 入口
bin/cli.js          — CLI 入口，参数解析
lib/
├── server.js       — Express 服务，路由注册
├── converter.js    — 协议转换引擎（核心）
├── config.js       — 配置管理、文件监控、路由解析
├── logger.js       — 日志记录，环形缓冲区，JSONL 持久化
├── admin-page.js   — 管理面板 HTML 渲染
└── admin.html      — 管理面板前端（Alpine.js + Tailwind CSS）
```

## 技术栈

- **运行时**：Node.js 18+
- **Web 框架**：Express
- **前端**：Alpine.js + Tailwind CSS（CDN，单页应用）
- **配置格式**：YAML（js-yaml）

## 日志

日志默认存储在 `~/.codex-proxy/` 目录（与配置文件同级）：

- `proxy.log` — 人类可读的文本格式
- `proxy.jsonl` — JSONL 格式，用于服务重启后恢复最近的日志到内存缓冲区

通过管理面板的设置页面可调整日志级别（DEBUG / INFO / WARN / ERROR）。

## License

MIT