mimo2codex Proxy Skill
mimo2codex Proxy Skill
Skill by
ara.so — Codex Skills collection.
由
ara.so开发的Skill——Codex Skills系列工具。
mimo2codex is a local proxy server that translates between OpenAI Codex's Responses API (
) and upstream LLM providers using Chat Completions API. It enables the latest Codex CLI and desktop app to work with:
- Xiaomi MiMo (V2.5 Pro, V2 Flash, V2 Omni)
- DeepSeek (V4 Pro, V4 Flash, Reasoner)
- Generic OpenAI-compatible providers (Qwen, GLM, Kimi, Ollama, vLLM, LM Studio)
Key features:
- Per-request model routing (send → MiMo, → DeepSeek)
- Automatic MiMo round-trip handling (v0.2.3+)
- Built-in admin webui at
http://127.0.0.1:8788/admin/
- Tool calling, web search, vision (model-dependent)
- sqlite persistence for logs and token stats
mimo2codex 是一款本地代理服务器,可在OpenAI Codex的Responses API(
)与使用Chat Completions API的上游大语言模型(LLM)提供商之间进行转换。它能让最新版Codex CLI和桌面应用与以下模型兼容:
- 小米MiMo(V2.5 Pro、V2 Flash、V2 Omni)
- DeepSeek(V4 Pro、V4 Flash、Reasoner)
- 通用OpenAI兼容提供商(Qwen、GLM、Kimi、Ollama、vLLM、LM Studio)
核心特性:
- 按请求路由模型(发送 → 转发至MiMo, → 转发至DeepSeek)
- 自动处理MiMo的往返逻辑(v0.2.3及以上版本)
- 内置管理WebUI,访问地址为
http://127.0.0.1:8788/admin/
- 工具调用、网页搜索、视觉能力(取决于模型支持情况)
- 使用sqlite持久化存储日志与token统计数据
npm (recommended)
npm(推荐方式)
bash
npm install -g mimo2codex
bash
npm install -g mimo2codex
Windows PowerShell
Windows PowerShell
Git clone (for development)
Git克隆(用于开发)
bash
git clone https://github.com/7as0nch/mimo2codex
cd mimo2codex
npm install
npm run build
npm link # registers `mimo2codex` globally
Requirements: Node.js ≥ 18
bash
git clone https://github.com/7as0nch/mimo2codex
cd mimo2codex
npm install
npm run build
npm link # 全局注册`mimo2codex`命令
要求:Node.js ≥ 18
1. Get API Keys
1. 获取API密钥
2. Configure Environment Variables
2. 配置环境变量
Built-in loader (v0.2.8+, recommended):
Initialize .env file in ~/.mimo2codex/
在~/.mimo2codex/目录下初始化.env文件
Edit ~/.mimo2codex/.env and add your keys:
编辑~/.mimo2codex/.env并添加你的密钥:
MIMO_API_KEY=sk-your-mimo-key
MIMO_API_KEY=sk-your-mimo-key
DS_API_KEY=sk-your-deepseek-key
DS_API_KEY=sk-your-deepseek-key
Start (auto-loads .env)
启动代理(自动加载.env文件)
mimo2codex
**Manual environment variables:**
```bash
export MIMO_API_KEY=sk-your-mimo-key
mimo2codex
export MIMO_API_KEY=sk-your-mimo-key
mimo2codex
export DS_API_KEY=sk-your-deepseek-key
mimo2codex --model ds
export DS_API_KEY=sk-your-deepseek-key
mimo2codex --model ds
Both providers (per-request routing)
同时启用两个提供商(按请求路由)
export MIMO_API_KEY=sk-your-mimo-key
export DS_API_KEY=sk-your-deepseek-key
mimo2codex
export MIMO_API_KEY=sk-your-mimo-key
export DS_API_KEY=sk-your-deepseek-key
mimo2codex
3. Configure Codex
3. 配置Codex
The startup banner prints the required snippets. Copy them to:
macOS/Linux:
Windows:
%USERPROFILE%\.codex\auth.json
%USERPROFILE%\.codex\config.toml
json
{
"base_url": "http://127.0.0.1:8788",
"api_key": "fake_api_key"
}
toml
wire_api = "responses"
model = "mimo-v2.5-pro"
启动时的横幅会显示所需的配置代码片段。将其复制到对应路径:
macOS/Linux:
Windows:
%USERPROFILE%\.codex\auth.json
%USERPROFILE%\.codex\config.toml
json
{
"base_url": "http://127.0.0.1:8788",
"api_key": "fake_api_key"
}
toml
wire_api = "responses"
model = "mimo-v2.5-pro"
Start proxy (MiMo default)
启动代理(默认使用MiMo)
Start with DeepSeek as default
启动代理并设置DeepSeek为默认提供商
Custom data directory
使用自定义数据目录
mimo2codex --data-dir /path/to/data
mimo2codex --data-dir /path/to/data
Disable reasoning display (still round-trips for MiMo)
禁用推理内容显示(仍会为MiMo保留往返逻辑)
mimo2codex --no-reasoning
mimo2codex --no-reasoning
Disable .env auto-loading
禁用.env自动加载
Initialize .env file
初始化.env文件
Print cc-switch snippets
打印cc-switch配置片段
mimo2codex print-cc-switch
mimo2codex print-cc-switch
Environment Variables
环境变量
| Variable | Provider | Required |
|---|
| MiMo | For MiMo models |
| or | DeepSeek | For DeepSeek models |
| Qwen | For Qwen models |
| GLM | For GLM models |
| Kimi | For Kimi models |
| OpenAI | For OpenAI models |
| - | Custom Codex config directory |
| 变量名 | 提供商 | 是否必填 |
|---|
| MiMo | 使用MiMo模型时必填 |
| 或 | DeepSeek | 使用DeepSeek模型时必填 |
| Qwen | 使用Qwen模型时必填 |
| GLM | 使用GLM模型时必填 |
| Kimi | 使用Kimi模型时必填 |
| OpenAI | 使用OpenAI模型时必填 |
| - | 自定义Codex配置目录 |
| Flag | Default | Description |
|---|
| | Proxy server port |
| | Proxy server host |
| | Default provider ( or ) |
| | Data/logs directory |
| | Hide reasoning from terminal |
| | Disable .env auto-loading |
| | Log level (debug/info/warn/error) |
| 参数 | 默认值 | 描述 |
|---|
| | 代理服务器端口 |
| | 代理服务器主机地址 |
| | 默认提供商(或) |
| | 数据/日志存储目录 |
| | 在终端隐藏推理内容 |
| | 禁用.env文件自动加载 |
| | 日志级别(debug/info/warn/error) |
MiMo:
- (default)
- (vision)
- (vision)
DeepSeek:
- Explicit match: If client sends , routes to MiMo (if key configured)
- Fallback: If client sends unknown model (e.g. ), routes to provider's default
- Provider disabled: If client sends but no , falls back to provider
Example routing with both keys configured:
bash
export MIMO_API_KEY=sk-mimo-key
export DS_API_KEY=sk-deepseek-key
mimo2codex # default fallback: mimo
- 精准匹配:如果客户端发送,则路由到MiMo(需已配置密钥)
- ** fallback逻辑**:如果客户端发送未知模型(例如),则路由到指定的默认提供商的默认模型
- 提供商未启用:如果客户端发送但未配置,则 fallback到指定的提供商
示例:配置双提供商密钥后的路由
bash
export MIMO_API_KEY=sk-mimo-key
export DS_API_KEY=sk-deepseek-key
mimo2codex # 默认fallback:mimo
In Codex config.toml:
在Codex的config.toml中:
model = "deepseek-v4-pro" → Routes to DeepSeek
model = "deepseek-v4-pro" → 路由到DeepSeek
model = "mimo-v2.5-pro" → Routes to MiMo
model = "mimo-v2.5-pro" → 路由到MiMo
model = "gpt-4o" → Falls back to mimo-v2.5-pro
model = "gpt-4o" → Fallback到mimo-v2.5-pro
Access at
http://127.0.0.1:8788/admin/
(port matches
)
访问地址:
http://127.0.0.1:8788/admin/
(端口与
参数一致)
- Dashboard: Token usage charts, cache hit rates, request stats
- Models: View all available models, test with ⚡Probe button
- Providers: View/edit provider configs from
- Logs: Browse chat logs with filtering
- Settings: Configure Codex paths, manage aliases
- Codex Enable: One-click write of and (replaces cc-switch)
- 仪表盘:token使用量图表、缓存命中率、请求统计
- 模型管理:查看所有可用模型,点击⚡Probe按钮测试连接
- 提供商管理:查看/编辑中的提供商配置
- 日志管理:浏览聊天日志并支持过滤
- 设置:配置Codex路径、管理模型别名
- Codex启用:一键写入和配置(替代cc-switch)
Codex Enable (v0.2.6+)
Codex启用(v0.2.6及以上版本)
- Open
http://127.0.0.1:8788/admin/
- Click "Codex Enable" tab
- Select model and click "Apply"
- Automatically backs up existing configs (first OpenAI backup preserved permanently)
Runtime override mode: Switch models without restarting Codex (experimental)
- 打开
http://127.0.0.1:8788/admin/
- 点击“Codex Enable”标签页
- 选择模型并点击“Apply”
- 自动备份现有配置(首次OpenAI配置会永久保留)
运行时覆盖模式:无需重启Codex即可切换模型(实验性功能)
Adding Custom Providers
添加自定义提供商
Edit
~/.mimo2codex/providers.json
(created after first run):
json
{
"providers": [
{
"name": "qwen",
"baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
"apiKeyEnvVar": "QWEN_API_KEY",
"defaultModel": "qwen3-max",
"models": ["qwen3-max", "qwen-turbo"],
"aliases": {
"qwen3": "qwen3-max"
},
"supportsWebSearch": true
}
]
}
Provider schema:
| Field | Type | Description |
|---|
| string | Unique provider identifier |
| string | OpenAI-compatible base URL |
| string | Environment variable name |
| string | Model ID for fallback |
| string[] | Supported model IDs |
| object | Model alias mappings |
| boolean | Enable web search tool |
编辑
~/.mimo2codex/providers.json
(首次运行后自动创建):
json
{
"providers": [
{
"name": "qwen",
"baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
"apiKeyEnvVar": "QWEN_API_KEY",
"defaultModel": "qwen3-max",
"models": ["qwen3-max", "qwen-turbo"],
"aliases": {
"qwen3": "qwen3-max"
},
"supportsWebSearch": true
}
]
}
提供商配置 schema:
| 字段 | 类型 | 描述 |
|---|
| string | 唯一提供商标识符 |
| string | OpenAI兼容的基础URL |
| string | 环境变量名称 |
| string | fallback使用的模型ID |
| string[] | 支持的模型ID列表 |
| object | 模型别名映射 |
| boolean | 是否启用网页搜索工具 |
json
{
"name": "ollama",
"baseUrl": "http://localhost:11434/v1",
"apiKeyEnvVar": "OLLAMA_API_KEY",
"defaultModel": "llama3.2",
"models": ["llama3.2", "qwen2.5-coder"],
"aliases": {
"llama": "llama3.2"
},
"supportsWebSearch": false
}
bash
export OLLAMA_API_KEY=ollama # Any non-empty value
mimo2codex
json
{
"name": "ollama",
"baseUrl": "http://localhost:11434/v1",
"apiKeyEnvVar": "OLLAMA_API_KEY",
"defaultModel": "llama3.2",
"models": ["llama3.2", "qwen2.5-coder"],
"aliases": {
"llama": "llama3.2"
},
"supportsWebSearch": false
}
bash
export OLLAMA_API_KEY=ollama # 任意非空值即可
mimo2codex
- Function tools: Custom JSON schemas
- local_shell: Execute shell commands
- MCP tools: Via parameter
- web_search: MiMo native (auto-enabled for MiMo, skipped for DeepSeek)
- 函数工具:自定义JSON schema
- local_shell:执行Shell命令
- MCP工具:通过参数调用
- web_search:MiMo原生支持(自动为MiMo启用,DeepSeek会忽略此工具调用)
MiMo: Translates Codex's
tool to MiMo's native builtin. Requires plugin activation in MiMo console.
DeepSeek: Web search not supported — tool calls are stripped.
MiMo:将Codex的
工具转换为MiMo的原生内置工具,需在MiMo控制台激活对应插件。
DeepSeek:不支持网页搜索——工具调用会被自动移除。
typescript
// Codex sends:
{
"model": "mimo-v2.5-pro",
"tools": [
{
"type": "function",
"function": {
"name": "get_weather",
"parameters": {
"type": "object",
"properties": {
"location": { "type": "string" }
}
}
}
}
]
}
// mimo2codex translates to MiMo Chat Completions:
{
"model": "mimo-v2.5-pro",
"tools": [
{
"type": "function",
"function": { ... }
}
]
}
typescript
// Codex发送的请求:
{
"model": "mimo-v2.5-pro",
"tools": [
{
"type": "function",
"function": {
"name": "get_weather",
"parameters": {
"type": "object",
"properties": {
"location": { "type": "string" }
}
}
}
}
]
}
// mimo2codex转换为MiMo Chat Completions请求:
{
"model": "mimo-v2.5-pro",
"tools": [
{
"type": "function",
"function": { ... }
}
]
}
Supported models:
Non-vision models (
,
, DeepSeek models): Images are auto-stripped with placeholder text.
支持的模型:
非视觉模型(
、
、DeepSeek系列模型):图片会被自动移除并替换为占位文本。
Example Vision Request
视觉请求示例
bash
codex
> Describe this image: /path/to/image.jpg
mimo2codex forwards the image URL/base64 to MiMo's vision model.
bash
codex
> Describe this image: /path/to/image.jpg
mimo2codex会将图片URL/base64转发至MiMo的视觉模型。
MiMo reasoning_content Round-Trip
MiMo reasoning_content 往返处理
Problem: MiMo requires every assistant message with
to echo back its
on the next turn. Without this, MiMo returns 400 errors or hallucinates.
Solution: mimo2codex ≥ 0.2.3 automatically stores and re-inserts
on subsequent turns.
问题:MiMo要求所有包含
的助手消息,在后续对话轮次中必须回显之前的
。如果缺少该内容,MiMo会返回400错误或产生幻觉。
解决方案:mimo2codex ≥ 0.2.3版本会自动存储并在后续对话轮次中重新插入
。
typescript
// Turn 1: MiMo returns
{
"role": "assistant",
"content": "",
"tool_calls": [...],
"reasoning_content": "I need to search the web"
}
// Turn 2: mimo2codex auto-injects reasoning_content
{
"role": "assistant",
"content": "",
"tool_calls": [...],
"reasoning_content": "I need to search the web" // ← auto-added
}
Flag:
hides reasoning from terminal but preserves round-trip.
typescript
// 第一轮:MiMo返回的内容
{
"role": "assistant",
"content": "",
"tool_calls": [...],
"reasoning_content": "I need to search the web"
}
// 第二轮:mimo2codex自动注入reasoning_content
{
"role": "assistant",
"content": "",
"tool_calls": [...],
"reasoning_content": "I need to search the web" // ← 自动添加
}
Multi-Provider Setup
多提供商配置
.env file (~/.mimo2codex/.env)
.env文件(路径:~/.mimo2codex/.env)
MIMO_API_KEY=sk-mimo-key
DS_API_KEY=sk-deepseek-key
QWEN_API_KEY=sk-qwen-key
MIMO_API_KEY=sk-mimo-key
DS_API_KEY=sk-deepseek-key
QWEN_API_KEY=sk-qwen-key
Codex config.toml - switch models dynamically:
Codex的config.toml - 动态切换模型:
model = "mimo-v2.5-pro"
model = "mimo-v2.5-pro"
model = "deepseek-v4-pro"
model = "deepseek-v4-pro"
model = "qwen3-max"
model = "qwen3-max"
Testing Model Connections
测试模型连接
Use the admin UI's ⚡Probe button:
- Open
http://127.0.0.1:8788/admin/
- Go to "Codex Enable" or "Models" tab
- Click ⚡Probe next to any model
- Validates key, baseUrl, and model ID end-to-end
使用管理UI的**⚡Probe**按钮:
- 打开
http://127.0.0.1:8788/admin/
- 进入“Codex Enable”或“Models”标签页
- 点击任意模型旁的⚡Probe按钮
- 端到端验证密钥、baseUrl和模型ID是否有效
Token Usage Tracking
Token使用量追踪
- Dashboard: Charts with cache hit overlay
- 仪表盘:带缓存命中率叠加的图表
- Green bars: Cache hits
- 绿色柱状图:缓存命中
- Gray ghosts: Prompt token totals
- 灰色虚影:提示token总量
- Window-wide hit rate summary
- 全局命中率汇总
Custom Codex Directory
自定义Codex目录
Via environment variable
通过环境变量配置
export CODEX_HOME=/custom/path
mimo2codex
export CODEX_HOME=/custom/path
mimo2codex
Via admin UI settings
通过管理UI设置
Navigate to Settings → Codex Path
进入Settings → Codex Path
400 Errors with MiMo (Tool Calls)
MiMo工具调用返回400错误
Symptom: MiMo returns 400 or agent rambles instead of calling tools.
Cause: Missing
round-trip.
Fix: Upgrade to mimo2codex ≥ 0.2.3
bash
npm update -g mimo2codex
症状:MiMo返回400错误,或代理无意义地输出内容而非调用工具。
解决方法:升级mimo2codex至≥0.2.3版本
bash
npm update -g mimo2codex
Provider Not Routing
提供商路由失败
Check:
- API key is set:
- Provider is enabled in startup banner
- Model ID matches provider's catalog (case-sensitive)
检查项:
- API密钥已设置:
- 启动横幅中显示提供商已启用
- 模型ID与提供商目录完全匹配(区分大小写)
Debug with log level
启用调试日志排查
mimo2codex --log-level debug
mimo2codex --log-level debug
Port Already in Use
端口已被占用
Update auth.json:
更新auth.json:
Web Search Not Working
网页搜索无法使用
MiMo: Activate the web search plugin in
MiMo Console → Plugins.
DeepSeek: Not supported (tool calls are stripped).
MiMo:在
MiMo控制台 → 插件中激活网页搜索插件。
DeepSeek:不支持网页搜索(工具调用会被移除)。
Image Generation (/hatch)
图片生成(/hatch命令)
Codex's
command calls OpenAI's
client-side — mimo2codex cannot intercept this. Workaround: Use
(see project README).
Codex的
命令会在客户端调用OpenAI的
接口——mimo2codex无法拦截该请求。解决方案:使用
(详见项目README)。
.env Not Loading
.env文件未加载
Verify file location
验证文件位置
Check file syntax (no spaces around =)
检查文件语法(=号周围不能有空格)
Disable auto-loading if needed
必要时禁用自动加载
Windows PowerShell Execution Policy
Windows PowerShell执行策略问题
powershell
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
powershell
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
Integration with cc-switch
与cc-switch集成
Generate cc-switch snippets:
bash
mimo2codex print-cc-switch
Output example:
toml
[mimo-v2.5-pro]
model = "mimo-v2.5-pro"
wire_api = "responses"
base_url = "http://127.0.0.1:8788"
api_key = "fake_api_key"
Copy to cc-switch config and use
to switch.
生成cc-switch配置片段:
bash
mimo2codex print-cc-switch
示例输出:
toml
[mimo-v2.5-pro]
model = "mimo-v2.5-pro"
wire_api = "responses"
base_url = "http://127.0.0.1:8788"
api_key = "fake_api_key"
将其复制到cc-switch配置文件中,使用
命令切换模型。
Default location:
(sqlite)
Stored data:
- Chat logs (request/response pairs)
- Token usage stats
- Cache hit metrics
- Model mappings
Custom location:
bash
mimo2codex --data-dir /custom/path
存储的数据:
- 聊天日志(请求/响应对)
- Token使用量统计
- 缓存命中指标
- 模型映射关系
自定义存储位置:
bash
mimo2codex --data-dir /custom/path
TypeScript API (for embedding)
TypeScript API(用于嵌入集成)
typescript
import { startServer } from 'mimo2codex';
const server = await startServer({
port: 8788,
host: '127.0.0.1',
dataDir: '~/.mimo2codex',
logLevel: 'info',
noReasoning: false,
loadEnv: true
});
// Server running at http://127.0.0.1:8788
typescript
import { startServer } from 'mimo2codex';
const server = await startServer({
port: 8788,
host: '127.0.0.1',
dataDir: '~/.mimo2codex',
logLevel: 'info',
noReasoning: false,
loadEnv: true
});
// 服务器运行在http://127.0.0.1:8788