内容
# 代码通用代理
[npm 包](https://www.npmjs.com/package/codex-universal-proxy)
在保留以下功能的同时，使用 Ollama、OpenRouter 和其他与 OpenAI 兼容的提供商与 Codex 配合使用：
* Codex 插件
* MCP 工具
* `tool_search`
* `apply_patch`
* 图片生成工具
代理在本地运行，将 Codex 特有的工具格式转换为与提供商兼容的函数调用，并将响应转换回 Codex 期望的格式。
> 该项目是非官方的且为实验性。Codex 工具格式可能会在版本之间发生变化。
## 支持的提供商和操作系统
内置提供商配置文件：
* Google AI Studio 和 Vertex AI
* NVIDIA
* OpenRouter
* Anthropic
* OpenAI
* Cohere
* Z.AI
* Moonshot
* DeepSeek
* xAI
* Ollama
还支持自定义提供商，只要它们公开了与 OpenAI 兼容的响应 API 或聊天完成 API。
支持的操作系统：
* 使用 launchd 的 macOS
* 使用 systemd 用户服务的 Linux
* 使用任务计划器的 Windows，具有每用户启动备用方案
## 安装
```bash
npm install -g codex-universal-proxy
codex-universal-proxy init
codex-universal-proxy install
```
从 `codex-ollama-proxy` 升级是自动的。第一个通用命令会将 `~/.codex/ollama-shape-proxy` 迁移到 `~/.codex/codex-universal-proxy`，复制遗留目录和引用文件，并替换遗留后台服务注册。如果旧运行时路径也是源代码checkout，则仅复制运行时拥有的配置文件、预设和发现缓存数据。
旧的 `codex-ollama-proxy` 可执行文件仍然是脚本和 shell 历史的别名。依赖于遗留 `ollama-launch-codex-app` 提供商的现有 Codex 任务将继续通过兼容性提供商入口工作。现有的附件文件将保留在其原始路径，以防止历史任务 JSONL 引用中断。
`install` 命令使用当前平台的原生每用户后台服务：
* macOS：`~/Library/LaunchAgents` 中的 launchd 代理
* Linux：`~/.config/systemd/user` 中的 systemd 用户服务
* Windows：使用任务调度器任务，在登录时运行
`restart`、`uninstall` 和 `logs` 命令使用相同的跨平台设置。在 Linux 上，必须可用的用户 systemd 会话。如果不安装后台服务，请使用 `codex-universal-proxy serve` 在终端中运行。
如果在安装过程中设置了 `CODEX_HOME`，则生成的后台服务将为未来的启动保留该目录。Linux 安装还会在定位 systemd 用户单元目录时遵循 `XDG_CONFIG_HOME`。
本地代理监听：
```text
http://127.0.0.1:11436
```
## 推荐的工作流程：提供商预设
预设保存了您的：
* 提供商端点
* 文本和图像模型
* API 密钥
* 响应或聊天完成适配器
* 路由和兼容性选项
创建每个提供商一次，然后通过名称启动：
```bash
codex-universal-proxy run PRESET_NAME
```
## Ollama 预设
Ollama 在 `http://127.0.0.1:11434/v1` 暴露了一个与响应兼容的本地 API。
```bash
codex-universal-proxy preset add ollama \
--url "http://127.0.0.1:11434/v1" \
--text-model "MODEL"
codex-universal-proxy run ollama
```
示例：
```bash
codex-universal-proxy preset add glm \
--url "http://127.0.0.1:11434/v1" \
--text-model "z-ai/glm-5.2"
codex-universal-proxy run glm
```
带有 Kimi 自动路由的 GLM：
```bash
codex-universal-proxy preset add glm-kimi \
--url "http://127.0.0.1:11434/v1" \
--text-model "glm-5.2:cloud" \
--image-model "kimi-k2.7-code:cloud" \
--auto-image
codex-universal-proxy run glm-kimi
```
## OpenRouter 预设
导出您的 OpenRouter 密钥：
```bash
export OPENROUTER_API_KEY="sk-or-..."
```
创建预设：
```bash
codex-universal-proxy preset add openrouter \
--provider openrouter \
--text-model "PROVIDER/MODEL" \
--api-key "$OPENROUTER_API_KEY"
```
运行它：
```bash
codex-universal-proxy run openrouter
```
示例：
```bash
codex-universal-proxy preset add openrouter-glm \
--url "https://openrouter.ai/api/v1" \
--text-model "z-ai/glm-5.2" \
--api-key "$OPENROUTER_API_KEY"
codex-universal-proxy run openrouter-glm
```
选定的 OpenRouter 模型必须支持所需的 API 和工具调用行为。
## Anthropic 预设
Anthropic 通过其与 OpenAI 兼容的聊天完成 API 得到支持。代理不会将请求转换为原生消息 API。
```bash
export ANTHROPIC_API_KEY="..."
codex-universal-proxy preset add claude \
--provider anthropic \
--text-model "claude-sonnet-5" \
--api-key "$ANTHROPIC_API_KEY"
codex-universal-proxy run claude
```
## OpenAI 预设
OpenAI 使用直接响应 API 直通：
```bash
export OPENAI_API_KEY="..."
codex-universal-proxy preset add openai \
--provider openai \
--text-model "gpt-5.6-sol" \
--api-key "$OPENAI_API_KEY"
codex-universal-proxy run openai
```
## 自定义响应 API 预设
对于任何公开 `POST /v1/responses` 的提供商：
```bash
export PROVIDER_API_KEY="..."
codex-universal-proxy preset add custom-responses \
--url "https://provider.example/v1" \
--text-model "MODEL" \
--api-key "$PROVIDER_API_KEY"
codex-universal-proxy run custom-responses
```
## 聊天完成提供商预设
一些提供商只公开：
```text
POST /v1/chat/completions
```
为这些提供商使用内置的聊天完成适配器：
```bash
export PROVIDER_API_KEY="..."
codex-universal-proxy preset add custom-chat \
--adaptor chat-completion \
--url "https://provider.example/v1" \
--text-model "MODEL" \
--api-key "$PROVIDER_API_KEY"
codex-universal-proxy run custom-chat
```
适配器将 Codex 响应 API 流量转换为聊天完成请求。
### NVIDIA 示例
```bash
export NVIDIA_API_KEY="nvapi-..."
codex-universal-proxy preset add nvidia \
--provider nvidia \
--text-model "z-ai/glm-5.2" \
--image-model "thinkingmachines/inkling" \
--auto-image \
--api-key "$NVIDIA_API_KEY"
codex-universal-proxy run nvidia
```
## 避免存储 API 密钥
要保存提供商配置而不存储其密钥：
```bash
codex-universal-proxy preset add openrouter \
--provider openrouter \
--text-model "PROVIDER/MODEL"
```
在激活预设时提供密钥：
```bash
codex-universal-proxy preset use openrouter \
--api-key "$OPENROUTER_API_KEY"
```
使用 `run PRESET_NAME` 时，预设中已包含其 API 密钥。
## 运行预设
在后台启动预设：
```bash
codex-universal-proxy run openrouter
```
在当前终端显示实时日志：
```bash
codex-universal-proxy run openrouter --foreground
```
应用预设而不启动代理：
```bash
codex-universal-proxy preset use openrouter --no-start
```
`run` 和 `preset use` 都配置了所选提供商并启动或重启所需的本地代理进程，除非使用 `--no-start`。
更改提供商后，请重启 Codex 或打开新的 Codex 线程。
### Windows 桌面模型选择器解决方法
Windows Codex 桌面应用程序可能无法加载代理生成的模型选择器目录。发生这种情况时，请使用硬编码的 Codex 模型覆盖激活预设：
```bash
codex-universal-proxy run glm-kimi --model-override "glm-5.2:cloud"
```
`--model-override` 将 `~/.codex/config.toml` 中的顶级 `model = "..."` 值写入文件中，强制每次 Codex 请求都使用该模型。它不会更改代理路由 `default_model`、`image_model` 或存储的预设。
## 文本和图像模型
预设可以使用单独的文本和图像模型：
```bash
codex-universal-proxy preset add multimodal \
--url "https://provider.example/v1" \
--text-model "TEXT_MODEL" \
--image-model "IMAGE_MODEL" \
--auto-image \
--api-key "$PROVIDER_API_KEY"
```
像往常一样运行：
```bash
codex-universal-proxy run multimodal
```
使用 `--auto-image` 时，当前用户回合或其工具输出中的图像将路由到图像模型。
对于只有一个多模态模型的提供商，请使用相同的模型：
```bash
codex-universal-proxy preset add multimodal \
--url "https://provider.example/v1" \
--text-model "MODEL" \
--image-model "MODEL" \
--auto-image \
--api-key "$PROVIDER_API_KEY"
```
在 `proxy-models.toml` 中设置 `persist_inline_images = true`，以缓存 `~/.codex/attachments` 下的内联图像，并用路径引用替换历史像素。生成的图像存储在同一个会话缓存中，而不是临时存储，因此它们的保存路径在后续回合中仍然可用。
持久性需要稳定的会话、线程、对话或提示缓存标识符；未使用 30 天的会话缓存将默认被惰性删除。可以通过以下方式更改相同的设置：
```bash
codex-universal-proxy route --persist-images --image-retention-days 30
```
## 图片生成
图片生成单独配置并应用于所有提供商预设。
### Gemini
```bash
codex-universal-proxy imagine \
--enable \
--service gemini \
--model "gemini-2.5-flash-image" \
--api-key "$GEMINI_API_KEY"
```
### OpenAI
```bash
codex-universal-proxy imagine \
--enable \
--service openai \
--model "gpt-image-2" \
--api-key "$OPENAI_API_KEY"
```
### Ollama
```bash
codex-universal-proxy imagine \
--enable \
--service ollama \
--model "x/z-image-turbo" \
--base-url "http://127.0.0.1:11434"
```
检查图片生成配置：
```bash
codex-universal-proxy imagine --doctor
```
代理使用 Codex 现有的 `generate_image` 工具。它不会检查普通提示并自动将它们转换为图片请求。
## 高级预设选项
预设还可以保存代理兼容性选项：
```bash
codex-universal-proxy preset add tuned \
--url "https://provider.example/v1" \
--text-model "MODEL" \
--dedupe-large-input \
--dedupe-min-chars 1024 \
--verbose-tools \
--enable-find-skill \
--no-stream-loop
```
可用的预设切换包括：
```text
--auto-image / --no-auto-image
--dedupe-large-input / --no-dedupe-large-input
--dedupe-min-chars N
--verbose-tools / --no-verbose-tools
--log-upstream-body / --no-log-upstream-body
--enable-find-skill / --no-enable-find-skill
--stream-loop / --no-stream-loop
```
运行时选项（例如 `--foreground`）保留在 `run` 或 `serve` 命令上，而不是存储在预设中。
## 代理修复的问题
Codex 可以使用 OpenAI 特有的命名空间、动态工具、托管工具和自由格式工具格式发送插件和 MCP 工具。
许多自定义提供商拒绝这些格式或会遇到诸如以下问题：
```text
unsupported call
MCP tools are visible but never invoked
tool_search aborts
namespace tools are rejected
apply_patch uses the wrong format
```
代理将这些工具转换为普通的提供商可调用函数，并在返回时将响应恢复为 Codex 格式。
### 命名空间和 MCP 工具
像这样的 Codex 工具：
```text
mcp__storefront_builder.list_storefront_build_sessions
```
可以公开给模型：
```text
mcp__storefront_builder__list_storefront_build_sessions
```
返回的调用被转换回 Codex 期望的名称空间和工具名称。
### `tool_search`
当提供商无法调用 Codex 原生的托管 `tool_search` 工具时，代理会公开一个常规函数桩并将结果映射回原生 `tool_search_call`。
`tool_search` 发现的延迟工具也可以在下一个请求中调用。
### `apply_patch`
Codex 可能将 `apply_patch` 公开为自定义或自由格式工具。代理在使周围工具列表与自定义提供商兼容的同时保留 Codex 需要的格式。
## 支持的提供商
* Ollama 兼容的响应 API 服务器
* 具有兼容 API 行为的 OpenRouter 模型
* 通过其与 OpenAI 兼容的聊天完成 API 实现 Anthropic
* 通过其原生响应 API 实现 OpenAI
* 公开 `POST /v1/responses` 的自定义提供商
* 通过内置适配器实现聊天完成提供商
* 本地响应 API 桩
图片生成可以独立使用 Gemini、OpenAI 或 Ollama。
## 有用的命令
```bash
codex-universal-proxy status
codex-universal-proxy upstream --status
codex-universal-proxy logs --tail 100
codex-universal-proxy restart
codex-universal-proxy run PRESET_NAME
codex-universal-proxy run PRESET_NAME --foreground
codex-universal-proxy switch openai
```
## Codex 技能
授予 Codex 此技能网址：
```text
https://raw.githubusercontent.com/bharat2808/codex-universal-proxy/main/skills/codex-universal-proxy/SKILL.md
```
然后询问 Codex：
```text
Install this skill and use it to set up codex-universal-proxy.
```
## 配置文件
运行时配置和日志存储在：
```text
~/.codex/codex-universal-proxy/proxy-models.toml
~/.codex/codex-universal-proxy/imagine.toml
~/.codex/codex-universal-proxy/proxy.log
```
默认情况下禁用调试日志记录：
```toml
verbose_tools = false
log_upstream_body = false
```
启用请求体日志记录时请谨慎，因为它可能包含提示、工具参数或其他敏感数据。
## 已知限制
* 此软件包与 OpenAI 无关。
* Codex 内部工具模式可能会更改。
* 兼容性取决于所选提供商和模型。
* 模型必须支持可靠的工具调用，以便插件和 MCP 工具正常工作。
* 一些提供商仅公开聊天完成，需要适配器。
* Web 搜索从 Ollama 云搜索、本地 Ollama 搜索到 DuckDuckGo HTML 搜索。
## 安装特定版本
```bash
npm install -g \
https://registry.npmjs.org/codex-universal-proxy/-/codex-universal-proxy-0.5.0.tgz
```
## 卸载
```bash
codex-universal-proxy switch openai
codex-universal-proxy uninstall
npm uninstall -g codex-universal-proxy
```
连接信息
猜你喜欢
暂无推荐服务器