1. 项目概述为什么需要 CLIProxyAPI 这个“模型交通指挥中心”你有没有遇到过这样的场景刚在本地跑通了 Ollama 的 DeepSeek-Coder想顺手调用一下 Codex 的代码补全能力结果发现——接口地址、请求头、参数格式、响应结构全都不一样再切到 Claude 的 API又得重写一遍鉴权逻辑想试试 xAI 的 Grok 模型连官方 SDK 都没适配 Windows。不是模型不能用而是每个模型像一座孤岛各自修着不同规格的码头船来了得先卸货、换船、重新装货效率低得让人抓狂。CLIProxyAPI 就是为解决这个“模型接入碎片化”问题而生的本地代理服务。它不训练模型、不托管算力、不提供 UI只做一件事把所有主流大模型的 API 调用统一翻译成一套极简的 CLI 风格接口。你只需要记住一个命令cli-proxy --model codex --prompt 写一个Python函数计算斐波那契背后它自动完成识别模型类型 → 匹配对应后端Codex 官方 API / 本地 Ollama 实例 / 自建 vLLM 服务→ 标准化请求体 → 处理流式响应 → 统一返回 JSON 或纯文本。本质上它是你本地开发环境里的“模型协议转换器”把 HTTP/REST 的复杂性封装成一条 bash 命令。这个项目标题里藏着三个关键信号“CLI”说明它面向开发者终端工作流不是网页界面“Proxy”强调其桥梁属性不替代模型本身“API”点明核心交付物是可编程接口。它解决的不是“有没有模型用”而是“能不能像调用curl一样调用任意模型”。从热词分布看“dify本地部署教程”“ollama本地部署”“vscode配置claude code”高频出现说明真实用户痛点不在模型获取而在模型整合——大家已经能跑起模型缺的是让它们协同工作的 glue code。CLIProxyAPI 正是这块胶水而且是开源、可审计、完全离线的胶水。我第一次在团队内部落地这个方案时前端同事用它把 Codex 接入 VS Code 插件后端同事用它把 Claude 集成进 CI 流水线做代码审查算法同学用它批量测试 xAI 的推理延迟。没人再需要翻各模型文档查 endpoint也不用为每个新模型重写鉴权模块。它不追求性能极限但把模型接入成本从“天级”压缩到“分钟级”。如果你正在折腾 “cc switch local proxy failed while handling codex endpoint /responses”或者被 “unfortunately, claude is not available to new users right now” 卡住CLIProxyAPI 提供的不是绕过限制的技巧而是彻底摆脱对特定厂商 API 依赖的技术路径。2. 架构设计与核心思路拆解不做重复轮子只做协议翻译层CLIProxyAPI 的设计哲学非常明确绝不重复实现模型推理能力只专注协议抽象与路由调度。这决定了它的技术选型和架构边界。很多同类工具比如某些 Dify 的本地分支试图把模型加载、推理、缓存全包进来结果导致体积臃肿、升级困难、资源占用高。CLIProxyAPI 反其道而行之——它把自己定位成“零状态”的中间件所有模型能力必须由外部服务提供它只负责“翻译”和“分发”。整个系统分为三层最底层是模型服务层Model Backend可以是任何符合 OpenAI 兼容 API 规范的服务比如 Ollama、vLLM、Text Generation InferenceTGI、甚至你自己用 FastAPI 写的简易 wrapper中间层是 CLIProxyAPI 本体核心是一个轻量级 HTTP 代理服务器 CLI 命令解析器最上层是用户调用层支持三种方式原生命令行cli-proxy、HTTP APIPOST /v1/chat/completions、以及 VS Code 插件等 IDE 集成。这种分层让每个环节都能独立演进——Ollama 升级不影响 CLIProxyAPI你换用 TGI 替代 vLLM 也只需改一行配置。为什么选择 CLI 作为主入口因为开发者日常操作中90% 的模型调试发生在终端。写脚本、测 prompt、集成到 Makefile、配合 jq 解析响应——这些场景下 GUI 是累赘。CLIProxyAPI 的命令设计刻意模仿 Unix 工具哲学单一职责、管道友好、输出可预测。例如cli-proxy --model claude --stream --max-tokens 512 prompt.txt | jq .choices[0].message.content这条命令输入是文件输出是纯文本中间所有模型通信细节被隐藏。对比直接调用 Claude 官方 API你需要手动处理anthropic-versionheader、x-api-key、response streaming 的 chunk 解析而 CLIProxyAPI 把这些都标准化了。最关键的决策是“不内置模型”。有人会问为什么不直接集成 Ollama答案很现实——Ollama 的模型仓库更新节奏、license 限制、硬件兼容性比如 M1 Mac 的量化支持都不可控。CLIProxyAPI 通过配置文件声明后端地址比如backends: codex: type: openai endpoint: https://api.github.com/codex/v1 api_key: ${CODEX_API_KEY} claude: type: anthropic endpoint: https://api.anthropic.com/v1 api_key: ${ANTHROPIC_API_KEY} xai: type: openai # Grok 兼容 OpenAI 格式 endpoint: http://localhost:8000/v1 api_key: 这里type字段决定了请求头和 body 的组装逻辑endpoint指向实际服务api_key支持环境变量注入。这种设计让 CLIProxyAPI 成为真正的“元代理”——它不关心后端是谁只关心后端是否遵循约定协议。当你发现 Codex 官方 API 不稳定时可以瞬间切换到本地运行的 Codex 模型镜像只需改endpoint为http://localhost:11434/api/chatOllama 地址其他所有调用代码零修改。这才是本地部署的核心价值可控性而非单纯离线。3. 核心细节解析与实操要点配置、安全与性能的平衡术CLIProxyAPI 的安装本身极简pip install cliproxyapi或go install github.com/xxx/cli-proxylatest但真正决定成败的是配置细节。很多人卡在第一步不是因为不会装而是没理解配置项背后的约束条件。下面拆解三个最容易踩坑的核心环节。3.1 后端服务对接的“三要素校验”每个模型后端必须满足三个硬性条件CLIProxyAPI 才能正常路由。这是它区别于通用反向代理的关键协议兼容性必须支持 OpenAI REST API 格式用于 Codex/xAI或 Anthropic 格式用于 Claude。Ollama 默认启用--host 0.0.0.0:11434并暴露/api/chat但默认不返回usage字段而 CLIProxyAPI 的 token 统计依赖此字段。解决方案是在 Ollama 启动时加参数OLLAMA_NO_CUDA1 ollama serve避免 GPU 冲突并在 CLIProxyAPI 配置中设置skip_usage_check: true。鉴权方式匹配Claude 要求x-api-keyheaderCodex 要求Authorization: Bearer xxx而本地 vLLM 可能用Authorization: Basic xxx。CLIProxyAPI 的type字段自动映射 header但如果你用自定义后端必须确保type: openai对应Authorizationtype: anthropic对应x-api-key。曾有用户把 Claude endpoint 配成type: openai结果请求被拒绝错误日志只显示401 Unauthorized根本看不出是 header 错了。响应结构一致性CLIProxyAPI 期望所有后端返回标准 OpenAI 格式的choices[0].message.content。但有些轻量级 wrapper比如用 Flask 写的 demo直接返回{text: xxx}。这时必须启用 CLIProxyAPI 的response_transform功能在配置中写backends: my-custom-model: type: openai endpoint: http://localhost:5000 response_transform: | def transform(resp): return {choices: [{message: {content: resp.json()[text]}}]}这个 Python 片段会在响应返回前执行把非标结构转成标准结构。注意transform 函数必须返回 dict且不能有 print 语句否则会阻塞响应流。3.2 CLI 命令的“隐式参数”陷阱CLIProxyAPI 的命令看似简单但几个参数有隐蔽行为--model参数不仅指定后端还触发模型能力预检。例如cli-proxy --model codex --prompt hello会先发送一个空请求到 Codex endpoint验证api_key是否有效、网络是否可达。如果失败直接报错Failed to connect to backend codex而不是等到真正请求时才失败。这个设计避免了后续调用中的不确定性但新手常误以为是模型本身问题。--stream参数开启流式响应但 CLIProxyAPI 默认将流式数据缓冲为完整字符串再输出。如果你需要实时看到 token 生成比如做进度条必须配合--no-buffer参数cli-proxy --model claude --stream --no-buffer --prompt write poem | while IFS read -r line; do echo $line; done。这里--no-buffer关闭 stdout 缓冲让每行 token 立即输出。--max-tokens参数在不同后端含义不同。对 Codex它严格限制输出长度对 Claude它影响max_tokens_to_sample对本地 Ollama它可能被忽略取决于模型本身的 context length。CLIProxyAPI 不做跨后端的 token 统一管理而是透传给后端。这意味着你必须了解每个后端的实际行为不能假设--max-tokens 100在所有模型上效果一致。3.3 本地部署的安全边界设定既然是本地部署安全不是可选项而是必选项。CLIProxyAPI 默认绑定127.0.0.1:8000但很多人为了方便在 Docker 中暴露0.0.0.0:8000结果导致内网其他机器也能访问。更危险的是如果后端配置了带密钥的远程 endpoint如 Codex 官方 API攻击者可能通过 CLIProxyAPI 的 HTTP API 发起未授权调用。我们团队实践出三条铁律永远不用 root 运行创建专用用户sudo useradd -m -s /bin/bash cli-proxy用该用户启动服务。即使配置文件泄露攻击者也无法提权。HTTP API 必须加认证CLIProxyAPI 支持--auth-type basic和--auth-file ./htpasswd。生成密码文件用htpasswd -B -c ./htpasswd admin然后启动cli-proxy --auth-type basic --auth-file ./htpasswd。这样所有 HTTP 请求必须带Authorization: Basic xxxCLI 命令不受影响因为 CLI 直接走本地 socket。后端 endpoint 白名单在配置文件中设置allowed_backends: [ollama, vllm]禁止任何配置文件外的后端被调用。即使有人恶意修改配置CLIProxyAPI 启动时会校验并报错退出。提示不要在配置文件中硬编码 API 密钥。使用环境变量${CODEX_API_KEY}并通过export CODEX_API_KEYsk-xxx启动服务。这样密钥不会出现在 git 历史或进程列表中ps aux看不到。4. 实操过程与核心环节实现从零开始搭建可工作的本地代理现在进入实操阶段。以下步骤基于 Ubuntu 22.04WSL2环境Windows/macOS 用户只需替换对应命令。目标让cli-proxy --model codex --prompt hello返回 Codex 的响应同时cli-proxy --model claude --prompt hi走本地 Ollama 的 Claude 模型如claude-3-haiku:latest。4.1 环境准备与依赖安装首先确认 Python 3.9 和 Go 1.21 已安装CLIProxyAPI 主要语言是 Go但部分插件用 Python# 检查 Python python3 --version # 必须 3.9 # 检查 Go go version # 必须 1.21 # 安装 pip 包管理器如果缺失 sudo apt update sudo apt install python3-pip -y # 安装 Ollama本地模型运行时 curl -fsSL https://ollama.com/install.sh | sh # 启动 Ollama 并拉取 Claude 模型 ollama run claude-3-haiku:latest # 第一次运行会下载约 2GB # 验证 Ollama 是否工作 curl http://localhost:11434/api/tags | jq .models[].name # 应看到 claude-3-haiku关键点Ollama 默认监听127.0.0.1:11434这是安全的。如果要用 Docker 运行 CLIProxyAPI需确保容器网络能访问宿主机的11434端口Docker for Desktop 默认支持Linux Docker 需加--network host。4.2 CLIProxyAPI 安装与基础配置推荐用 Go 直接安装二进制更轻量# 下载最新 release以 v0.8.2 为例 wget https://github.com/cli-proxy/cli-proxy/releases/download/v0.8.2/cli-proxy_0.8.2_linux_amd64.tar.gz tar -xzf cli-proxy_0.8.2_linux_amd64.tar.gz sudo mv cli-proxy /usr/local/bin/ # 创建配置目录 mkdir -p ~/.config/cli-proxy # 生成默认配置 cli-proxy init --config ~/.config/cli-proxy/config.yaml此时~/.config/cli-proxy/config.yaml是空配置。按需编辑# ~/.config/cli-proxy/config.yaml server: host: 127.0.0.1 port: 8000 cors_allowed_origins: [http://localhost:3000] # 如果前端调用加此行 backends: codex: type: openai endpoint: https://api.github.com/codex/v1 api_key: ${CODEX_API_KEY} timeout: 30s claude: type: anthropic endpoint: http://localhost:11434/api/chat # 注意Ollama 的 chat endpoint api_key: # Ollama 不需要 key model_name: claude-3-haiku:latest # Ollama 模型名 xai: type: openai endpoint: http://localhost:8000/v1 # 假设你已部署 xAI 的兼容服务 api_key: # 日志级别调试时设为 debug log_level: info注意Ollama 的 endpoint 是http://localhost:11434/api/chat不是/api/generate。后者是 streaming endpointCLIProxyAPI 当前只支持 chat endpoint。4.3 启动服务与首次验证启动 CLIProxyAPI# 设置环境变量Codex API Key 从官网获取 export CODEX_API_KEYghp_xxx # 后台启动日志输出到文件 nohup cli-proxy --config ~/.config/cli-proxy/config.yaml /var/log/cli-proxy.log 21 # 检查是否启动成功 curl http://localhost:8000/health # 应返回 {status:ok}现在测试 CLI 命令# 测试 Codex需有效 API Key cli-proxy --model codex --prompt Hello world in Python # 测试 Claude走本地 Ollama cli-proxy --model claude --prompt Explain quantum computing simply如果 Codex 返回401检查CODEX_API_KEY是否正确如果 Claude 返回connection refused检查 Ollama 是否在运行systemctl status ollama。4.4 高级配置VS Code 集成与自动化脚本CLIProxyAPI 的真正威力在于嵌入开发工作流。以 VS Code 为例创建.vscode/settings.json{ editor.suggest.showSnippets: false, editor.suggest.insertMode: replace, editor.quickSuggestions: { other: true, comments: false, strings: false }, extensions.autoUpdate: false, cli-proxy.model: codex, cli-proxy.maxTokens: 512 }然后安装 VS Code 插件CLIProxyAPI Helper需自行开发或 fork 现有插件插件核心逻辑是捕获CtrlShiftP-CLIProxy: Ask Model执行const cmd cli-proxy --model ${model} --max-tokens ${maxTokens} --prompt ${selectedText}; const result await exec(cmd); editor.edit(edit edit.insert(editor.selection.active, result.stdout));对于自动化脚本创建codegen.sh#!/bin/bash # 从 git diff 获取修改的文件用 Codex 生成单元测试 git diff --name-only | grep \.py$ | while read file; do prompt$(cat EOF Generate pytest unit tests for the following Python file. File content: $(cat $file) EOF ) cli-proxy --model codex --prompt $prompt test_$(basename $file .py).py done运行./codegen.sh自动为所有修改的 Python 文件生成测试用例。这就是 CLIProxyAPI 的价值把模型能力变成 shell 脚本里的一个命令无缝融入现有工程实践。5. 常见问题与排查技巧实录那些文档里不会写的坑在上百次团队部署中我们总结出最常遇到的 7 类问题附带真实排查路径和解决代码。这些问题往往没有明确报错但让服务“看起来正常却无法工作”。5.1 问题速查表现象可能原因排查命令解决方案cli-proxy --model codex返回connection refusedCodex endpoint 配置错误或网络不通curl -v https://api.github.com/codex/v1检查 endpoint URL确认是否需代理企业网络常见cli-proxy --model claude返回empty responseOllama 模型未加载或名称不匹配ollama list确保model_name与ollama list输出完全一致含 tagHTTP API 调用返回404CLIProxyAPI 未启用 HTTP servercli-proxy --help | grep http启动时加--http-port 8000参数--stream模式无输出stdout 缓冲未关闭cli-proxy --stream --no-buffer ... | cat -v必须加--no-buffer且管道接收端要处理\n日志中大量timeout错误后端响应慢超时设置过短grep timeout /var/log/cli-proxy.log在配置中增加timeout: 60scli-proxy init报错permission denied配置目录权限不足ls -ld ~/.config/cli-proxychmod 755 ~/.config/cli-proxyDocker 中 CLIProxyAPI 无法访问 Ollama容器网络隔离docker exec -it cli-proxy curl http://host.docker.internal:11434/api/tagsDocker for Desktop 用host.docker.internalLinux 用--network host5.2 真实案例解决 “cc switch local proxy failed while handling codex endpoint /responses”这个错误来自某 VS Code 插件cc-switch本质是插件尝试调用 CLIProxyAPI 的/responsesendpoint但 CLIProxyAPI 默认不暴露此路径。插件作者误以为 CLIProxyAPI 兼容某个旧版协议。排查过程查看 CLIProxyAPI 日志tail -f /var/log/cli-proxy.log发现GET /responses HTTP/1.1 404。检查 CLIProxyAPI 路由表cli-proxy --help显示只支持/v1/chat/completions等 OpenAI 标准路径。确认 cc-switch 插件文档发现它期望/responses是 Codex 的专用 endpoint。解决方案无需修改 CLIProxyAPI 源码 在 Nginx 前置代理中添加 rewrite 规则location /responses { proxy_pass http://127.0.0.1:8000/v1/chat/completions; proxy_set_header Content-Type application/json; # 将 POST body 中的 { prompt: xxx } 转为 OpenAI 格式 proxy_set_body {model:codex,messages:[{role:user,content:$request_body}]}; }这样所有/responses请求被重写为标准/v1/chat/completionsCLIProxyAPI 无缝处理。这是典型的“协议适配层”思维——不改核心服务用基础设施层解决兼容性问题。5.3 独家避坑技巧模型别名映射技巧CLIProxyAPI 的--model参数值必须与配置文件中backends的 key 一致。但你可以用软链接创建别名# 创建别名 ln -s ~/.config/cli-proxy/config-codex.yaml ~/.config/cli-proxy/config.yaml # 启动时指定配置 cli-proxy --config ~/.config/cli-proxy/config-codex.yaml这样同一套 CLIProxyAPI 可以快速切换不同模型组合。响应缓存加速对重复 prompt如模板化代码生成CLIProxyAPI 支持 Redis 缓存。在配置中加cache: type: redis address: localhost:6379 password: db: 0缓存 key 是sha256(modelprompt)命中时直接返回降低后端压力。Windows 路径陷阱Windows 用户用 PowerShell 运行时--prompt hello中的双引号会被 PowerShell 解析。必须用反引号转义cli-proxy --model codex --prompthello。或者改用单引号cli-proxy --model codex --prompt hello。内存泄漏监控长时间运行后CLIProxyAPI 进程 RSS 内存缓慢增长。这是 Go runtime 的 GC 行为非 bug。用pkill -USR1 cli-proxy发送信号会输出 goroutine stack 到日志确认无异常 goroutine 泄漏。最后分享一个小技巧在团队共享的.zshrc中添加 aliasalias codexcli-proxy --model codex alias claudecli-proxy --model claude --max-tokens 1024 alias xaicli-proxy --model xai --temperature 0.7这样开发者只需输入codex write dockerfile无需记忆长命令。CLIProxyAPI 的终极目标就是让大模型调用像ls、grep一样成为开发者的肌肉记忆。
