让 Codex 接入任意支持 chat/completions 协议及 responses 协议的 llm api
Codex 使用 Responses 协议工作，但很多模型供应商仍以 Chat Completions 或自定义 Responses 网关提供服务。codex-shift 提供一个本地适配层，把这些上游统一成 Codex 可直接使用的 Responses 入口，并补齐模型目录、上下文窗口和 provider 路由能力。
它支持这些功能：
- responses 协议转换：将 chat/completions 协议和 responses 协议的 api 统一转换为
POST /v1/responses。 - 多 Provider 路由：同一配置中管理 DeepSeek、Qwen、MiMo、内部网关等上游，并按模型名自动选择 provider。
- Codex 模型目录：通过实现 responses 协议的
/models接口 暴露 Codex 兼容的ModelInfo，让自定义模型获得真实上下文窗口，比如开启 1M 上下文窗口，而不是 codex 内置的 272k。 - 本地热管理：内置本地控制台，通过
/admin进入控制台，图形界面化增删 provider、调整权重、维护模型列表与上下文窗口并保存配置，不需要重启进程。 - 错误语义统一：上游超时、非法 JSON、API 错误会转换为 Responses 风格错误响应。
- 纯本地转换：轻量，简洁的本地转换，不做路由和转换以外的多余动作，性能几乎无损。
- Provider 内模型映射：例如对外暴露
gpt-5.5，但在某个 provider 内部实际发往mimo-v2.5-pro或deepseek-v4-pro。
chat_completions出站：将 OpenAI Responses 请求转换为 Chat Completions，并把响应转换回 Responses。responses出站：上游同为 Responses 协议时进入全透传模式，仅注入 API Key，并保留/models上下文代理能力。- 支持流式与非流式请求，流式 SSE 会转换为 Responses 事件序列。
models[].mapped_model支持在每个 provider 内把入站模型名映射为上游模型名。- 多个 provider 声明同一模型时，按
weight做加权选择。 /models基于内置 CodexModelInfo模板克隆条目，只覆盖 slug 与上下文窗口等元数据。
- 支持 function tool 双向映射，包含 Codex namespace 展平与回程还原。
- Chat 出站可按 provider 配置透传
web_search。 reasoning.effort会在 Chat 出站时映射为reasoning_effort，Responses 透传时保持原样。
git clone git@github.com:ahtcfg24/codex-shift.git
cd codex-shift
cp .env.example .env
$EDITOR .env
./start.shstart.sh 会自动准备虚拟环境、安装依赖、复制 config.yaml、加载项目 .env、处理端口占用，并默认通过系统 service 启动服务。macOS 使用 LaunchAgent，重启后用户登录即自动拉起；Linux 使用 systemd user service，并尝试启用 linger 以支持重启后自动启动。启动完成后访问 GET /health 验证服务状态。
./start.sh # 启动/重启 service 并启用自启动
./start.sh --log-level debug # 用 debug 日志参数启动/重启 service
./start.sh status # 查看 service 运行状态
./start.sh restart # 重启 service
./start.sh stop # 停止当前 service 实例,自启动配置保留默认监听地址来自 config.yaml 的 server.host 与 server.port。示例配置使用 127.0.0.1:8080，本地控制台地址为：
http://127.0.0.1:8080/admin
如果 start.sh 因端口占用自动选择了新端口，请使用启动输出中的实际端口访问控制台。
curl http://127.0.0.1:8080/v1/responses \
-H 'Content-Type: application/json' \
-d '{
"model": "gpt-5.5",
"input": [{"role": "user", "content": "Hello!"}],
"stream": false
}'| 文档 | 内容 |
|---|---|
| 用户手册 | 从安装、配置到运行维护的完整目录 |
| 软件介绍 | 项目定位、核心概念与工作流程 |
| 安装与启动 | 环境要求、启动脚本、健康检查 |
| Provider 配置 | config.yaml 结构、字段说明与路由规则 |
| API 端点 | /v1/responses、/models、/health、/admin |
| Codex 集成 | 让 Codex 读取本代理的模型目录与上下文窗口 |
| 运行维护 | 控制台、日志、端口与排错 |
| FAQ | 常见问题、限制与安全提示 |
codex_shift/
├── codex_shift/ # FastAPI 服务、配置加载、协议转换与上游转发
├── tests/ # 单元测试与协议转换测试
├── docs/user-manual/zh/ # 中文用户手册
├── config.example.yaml # 配置示例
├── .env.example # 环境变量示例
└── start.sh # service 启动与自启动脚本
python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
pip install pytest
pytest开发配置请从 config.example.yaml 复制为 config.yaml，真实 API Key 建议写入 .env。config.yaml 与 .env 已在 .gitignore 中排除，请不要提交真实密钥。
欢迎通过 Issue 或 Pull Request 改进文档、协议转换兼容性、测试覆盖和 provider 示例。详细流程见 CONTRIBUTING.md。提交前请确保：
- 不提交真实 API Key、内部域名或敏感配置。
- 新增协议行为时同步更新用户手册与测试。
- 文档中的命令、路径和端点已在本仓库中验证。