# codex_api

**Repository Path**: chees_cn/codex_api

## Basic Information

- **Project Name**: codex_api
- **Description**: codex的国内api接口转发服务，适用于服务端部署，然后给本地的codex使用，支持deepseek
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-07
- **Last Updated**: 2026-06-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Codex API — DeepSeek Chat Proxy Service

基于 DeepSeek Chat Completions API 的流式对话代理服务，完全兼容 OpenAI API 格式（Chat Completions 和 Responses API），可作为 Codex CLI、Cursor、Continue、Aider 等 AI 编程工具的后端代理。

## 功能特性

- **双 API 兼容**：同时支持 OpenAI Chat Completions API（`/v1/chat/completions`）和 Responses API（`/v1/responses`）格式
- **流式响应**：支持 SSE 流式和非流式响应，实时返回生成内容
- **工具调用（Tool Calls）**：自动修复多种非标准工具格式，支持多工具并行调用
- **系统指令**：通过 `instructions` 参数或 `system` 角色消息注入系统提示
- **模型名称映射**：客户端传入任意模型名（如 `gpt-4`），服务端统一映射为指定模型
- **对话历史续接**：支持 `previous_response_id`，基于缓存实现多轮对话续接（Responses API）
- **多种输入格式**：支持 `messages`（Chat 格式）、`input`（Responses 格式字符串/数组）、`input` + `previous_response_id`
- **角色自动规范化**：将 `developer` 等非标准角色转换为 `system`
- **内容格式自动提取**：从 `content` 数组/对象/字符串中智能提取文本
- **独立 function_call 项处理**：自动附加到最近一条 assistant 消息
- **请求日志记录**：带时间戳的日志输出，支持调试日志保存到文件
- **健康检查端点**：`/health` 用于服务状态监控
- **跨域支持（CORS）**：内置 CORS 中间件

## 快速开始

### 1. 安装依赖

```bash
npm install
```

### 2. 配置环境变量

复制 `.env.example` 为 `.env`，填入你的 API Key：

```bash
copy .env.example .env
```

编辑 `.env`（参考下方环境变量说明）。

### 3. 启动服务

```bash
npm start
```

服务将在 `http://127.0.0.1:8000` 启动，监听 `0.0.0.0`。

## API 端点

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/v1/chat/completions` | Chat Completions API（流式/非流式） |
| POST | `/v1/responses` | Responses API（流式/非流式，兼容格式） |
| DELETE | `/v1/sessions/:sessionId` | 清除会话缓存 |
| GET | `/health` | 健康检查 |

## 环境变量

| 变量名 | 必填 | 默认值 | 说明 |
|--------|------|--------|------|
| `DEEPSEEK_API_KEY` | 是 | — | DeepSeek API Key |
| `DEEPSEEK_BASE_URL` | 否 | `https://api.deepseek.com` | DeepSeek API 基础 URL |
| `MODEL_NAME` | 否 | `null` | 模型名称映射（见下方说明） |
| `PORT` | 否 | `8000` | 服务端口 |

### 模型名称映射

设置 `MODEL_NAME` 环境变量后，无论客户端请求中传入的 `model` 字段是什么（如 `gpt-4`、`gpt-3.5-turbo`、`deepseek-chat` 等），服务都会统一使用配置的模型名称转发请求。

```env
# 设为 deepseek-chat，无论请求传什么模型，都用 deepseek-chat
MODEL_NAME=deepseek-chat
```

这样客户端可以使用任何模型名称（如 `gpt-4`），服务会自动映射为 `deepseek-chat`，方便对接各种 AI 编程工具。

## 客户端配置指南

本服务完全兼容 OpenAI API 格式，可直接用作 Codex CLI、Cursor、Continue、Aider 等工具的后端。

### Codex CLI

通过环境变量配置：

```bash
set OPENAI_API_KEY=sk-your-deepseek-api-key
set OPENAI_BASE_URL=http://127.0.0.1:8000/v1
codex "Hello, world!"
```

或在 `~/.codex/config.json` 中配置代理模式（参考 Codex CLI 文档）。

### Cursor

在 Cursor Settings → Models 中添加自定义模型：
- **Model**: `deepseek-chat`
- **Base URL**: `http://127.0.0.1:8000/v1`
- **API Key**: `sk-your-deepseek-api-key`

### Continue (VS Code)

在 `~/.continue/config.json` 中添加 OpenAI 兼容 provider。

### Aider

```bash
aider --model openai/deepseek-chat --openai-api-base http://127.0.0.1:8000/v1
```

### 通用 OpenAI SDK

```javascript
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'sk-your-deepseek-api-key',
  baseURL: 'http://127.0.0.1:8000/v1',
});

// Chat Completions — 非流式
const response = await client.chat.completions.create({
  model: 'deepseek-chat',
  messages: [{ role: 'user', content: 'Hello!' }],
  stream: false,
});

// Chat Completions — 流式
const stream = await client.chat.completions.create({
  model: 'deepseek-chat',
  messages: [{ role: 'user', content: 'Hello!' }],
  stream: true,
});
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content || '');
}
```

## 请求示例

### Chat Completions API

```bash
# 非流式请求
curl http://127.0.0.1:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-deepseek-api-key" \
  -d '{
    "model": "deepseek-chat",
    "messages": [
      { "role": "system", "content": "你是一个有帮助的助手。" },
      { "role": "user", "content": "你好" }
    ],
    "temperature": 0.7,
    "stream": false
  }'

# 流式请求（SSE）
curl http://127.0.0.1:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-deepseek-api-key" \
  -d '{
    "model": "deepseek-chat",
    "messages": [{ "role": "user", "content": "你好" }],
    "stream": true
  }'
```

### Responses API

```bash
# 使用 input 字符串
curl http://127.0.0.1:8000/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-deepseek-api-key" \
  -d '{
    "input": "Hello, what is 2+2?",
    "stream": true
  }'

# 使用 input 数组（多轮对话）
curl http://127.0.0.1:8000/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-deepseek-api-key" \
  -d '{
    "input": [
      { "role": "user", "content": "Hello" },
      { "role": "assistant", "content": "Hi! How can I help?" },
      { "role": "user", "content": "What is 2+2?" }
    ],
    "stream": false
  }'

# 使用 previous_response_id 续接对话
curl http://127.0.0.1:8000/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-deepseek-api-key" \
  -d '{
    "input": "Tell me more",
    "previous_response_id": "resp_abc123...",
    "stream": true
  }'
```

### 工具调用（Tool Calls）

```bash
curl http://127.0.0.1:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-deepseek-api-key" \
  -d '{
    "messages": [{ "role": "user", "content": "北京天气怎么样？" }],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "获取天气信息",
          "parameters": {
            "type": "object",
            "properties": {
              "city": { "type": "string", "description": "城市名" }
            },
            "required": ["city"]
          }
        }
      }
    ],
    "stream": false
  }'
```

服务会自动修复多种非标准工具格式：
- **扁平格式** `{name, description, parameters}` → 标准 `{type: "function", function: {...}}`
- **非标准 type**（如 `tool_search`）→ 转为 `function` 类型
- **function 为字符串** → 转为对象格式

### 流式响应格式（Responses API SSE）

```
event: response.created
data: {"type":"response.created","response":{"id":"resp_xxx","status":"in_progress",...}}

event: response.output_item.added
data: {"type":"response.output_item.added","item":{"type":"message",...}}

event: response.output_text.delta
data: {"type":"response.output_text.delta","delta":"你好"}

event: response.output_text.done
data: {"type":"response.output_text.done","text":"你好！有什么可以帮助你的？"}

event: response.completed
data: {"type":"response.completed","response":{"status":"completed",...}}
```

## 内部架构

### 核心处理流程

1. **请求解析** — 从 `messages`（Chat 格式）或 `input`（Responses 格式）提取消息列表
2. **消息规范化** — 提取文本内容、转换角色、附加独立 `function_call` 到 assistant 消息
3. **工具格式修复** — 自动检测并修复多种非标准工具格式
4. **系统指令处理** — 从 `instructions` 参数或 `system` 角色消息提取，注入到 API 调用
5. **模型名称映射** — 如果配置了 `MODEL_NAME`，覆盖请求中的 `model` 字段
6. **流式输出转换** — 将 DeepSeek Chat Completions 流转换为 Chat Completions SSE 或 Responses API SSE 格式
7. **响应缓存** — 缓存对话历史，支持 `previous_response_id` 续接

### 关键技术点

- **Responses API 兼容**：`/v1/responses` 端点将 DeepSeek 的 Chat Completions 流实时转换为 Responses API 的 SSE 事件流（`response.created` → `response.output_text.delta` → `response.completed`），无需等待完整响应
- **工具调用流式重建**：从流式 delta 中增量重建完整的 `tool_calls`，支持多工具调用
- **调试日志**：流式 Responses API 响应自动保存到 `debug_responses_stream_*.txt` 文件

## 开发

```bash
# 安装依赖
npm install

# 启动服务
npm start

# 运行测试
node test_api.js           # 完整接口测试
node test_responses_api.js # Responses API 专项测试
node test_codex_tools.js   # Codex 工具格式兼容测试
node test_tools_format.js  # 工具格式修复测试
node test_api_direct.js    # 直接 API 调用测试
node test_edge_cases.js    # 边界情况测试
node test_tool_search.js   # 工具搜索测试
```

## 技术栈

- **Node.js** — 运行时
- **Express** — HTTP 服务框架
- **OpenAI Node.js SDK** — DeepSeek API 客户端（兼容 OpenAI 格式）
- **dotenv** — 环境变量管理
- **cors** — 跨域支持

## License

MIT