CLIProxyAPI 本地部署指南:Go 编译到接口测试全流程

2026-01-24 约 1676 字预计阅读 4 分钟

本文将教你:
检查和安装 Go 语言环境
从 GitHub 克隆并编译 CLIProxyAPI
配置 API Key 和监听端口
启动服务并测试 AI 模型接口
常见问题的故障排查

什么是 CLIProxyAPI?

CLIProxyAPI 是一个基于 Go 语言开发的轻量级 AI 代理网关,它为 Gemini、Claude、OpenAI 等多种 AI 服务提供统一的 OpenAI 兼容 API 接口。通过 CLIProxyAPI,你可以在本地搭建自己的 AI 接口转发服务,实现多模型切换、请求日志记录、访问控制等功能。特别适合开发环境测试和多账号管理场景。

想要在本地运行属于自己的 AI 代理网关？CLIProxyAPI 基于 Go 语言开发，部署非常轻量便捷。本文将手把手带你完成从源码下载到本地启动的全过程。

1. 环境准备

CLIProxyAPI 是用 Go 语言编写的，因此在开始之前，你需要确保本地环境已经安装了 Go 语言开发环境。

打开终端，输入以下命令检查：

go version

如果输出了版本号（例如 go version go1.23.0 darwin/arm64），说明环境准备就绪。
如果提示命令未找到，请前往 Go 官网下载并安装最新版本。

2. 下载源码

使用 Git 将项目源码克隆到本地：

git clone https://github.com/router-for-me/CLIProxyAPI.git

进入项目目录：

cd CLIProxyAPI

3. 基础配置

项目提供了一个配置模版，我们需要将其复制一份作为正式配置文件。

cp config.yaml.example config.yaml

建议：此时可以用文本编辑器打开 config.yaml，根据需要修改监听端口（默认 8317）或配置 API Key。

4. 编译项目

执行 Go 编译命令，生成可执行文件 cli-proxy-api：

go build -o cli-proxy-api main.go

如果编译成功，目录下会生成一个名为 cli-proxy-api（Windows 下为 cli-proxy-api.exe）的文件。

5. 启动服务

直接运行编译好的可执行文件：

./cli-proxy-api

你会看到类似以下的日志输出，表明服务已经成功启动并监听在指定端口：

INFO[0000] Starting server on :8317...

6. 接口测试

服务启动后，它对外提供兼容 OpenAI 格式的 API。我们可以重新打开一个终端窗口，使用 curl 快速测试一下。

测试 Gemini 模型：

curl http://localhost:8317/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key-1" \
  -d '{
    "model": "gemini-2.5-flash",
    "messages": [{"role": "user", "content": "Hello, this is a test check."}]
  }'

如果返回了 JSON 格式的回复，恭喜你，你的本地 AI 代理网关已经搭建成功！现在你可以将 http://localhost:8317 配置到任何支持 OpenAI 接口的客户端（如 Chatbox, NextChat）中使用了。

进阶配置

配置多个 API Key

编辑 config.yaml 文件,在 api-keys 数组中添加多个密钥:

api-keys:
  - "key-for-team-a"
  - "key-for-team-b"
  - "key-for-personal-use"

不同的客户端可以使用不同的 Key,便于追踪和管理。

配置日志级别

log:
  level: "debug"  # 可选: debug, info, warn, error
  file: "./logs/cliproxyapi.log"

后台运行服务

使用 nohup (Linux/Mac):

nohup ./cli-proxy-api > output.log 2>&1 &

使用 systemd (Linux): 创建服务文件 /etc/systemd/system/cliproxyapi.service:

[Unit]
Description=CLIProxyAPI Service
After=network.target

[Service]
Type=simple
User=your-username
WorkingDirectory=/path/to/CLIProxyAPI
ExecStart=/path/to/CLIProxyAPI/cli-proxy-api
Restart=on-failure

[Install]
WantedBy=multi-user.target

启动服务:

sudo systemctl enable cliproxyapi
sudo systemctl start cliproxyapi
sudo systemctl status cliproxyapi

常见问题 (FAQ)

Q1: 编译时提示 “go: command not found”

A: 说明 Go 环境未正确安装或未添加到 PATH。解决步骤:

# 1. 下载并安装 Go (访问 https://go.dev/dl/)
# 2. 验证安装
go version

# 3. 如果仍然找不到,检查 PATH
echo $PATH | grep go

# 4. 手动添加到 PATH (以 macOS/Linux 为例)
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.zshrc
source ~/.zshrc

Q2: 编译时提示依赖下载失败

A: 可能是网络问题或 Go Module 代理配置。解决方法:

# 设置国内 Go Module 代理
export GOPROXY=https://goproxy.cn,direct

# 清理缓存重新编译
go clean -modcache
go build -o cli-proxy-api main.go

Q3: 启动后无法访问 8317 端口

A: 可能的原因和解决方案:

# 1. 检查端口是否被占用
lsof -i :8317
# 或
netstat -an | grep 8317

# 2. 如果被占用,修改 config.yaml 中的端口
port: 8318  # 改为其他端口

# 3. 检查防火墙规则
# macOS
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --add /path/to/cli-proxy-api
# Linux
sudo ufw allow 8317/tcp

Q4: 接口返回 “Invalid API Key”

A: 检查以下几点:

# 1. 确认 config.yaml 中配置了 api-keys
cat config.yaml | grep api-keys

# 2. 确认请求头中的 Authorization 格式正确
# ✅ 正确: "Authorization: Bearer your-key-here"
# ❌ 错误: "Authorization: your-key-here"

# 3. 确认 Key 与配置文件中的完全一致 (区分大小写)

Q5: 如何查看详细的请求日志?

A: 有几种方式:

方式一: 直接在终端查看实时输出

./cli-proxy-api

方式二: 配置日志文件并查看

# config.yaml
log:
  level: "debug"
  file: "./logs/app.log"

# 实时查看日志
tail -f ./logs/app.log

方式三: 使用 curl 的 verbose 模式测试

curl -v http://localhost:8317/v1/chat/completions \
  -H "Authorization: Bearer your-key" \
  -d '{"model":"gemini-2.5-flash","messages":[{"role":"user","content":"test"}]}'

Q6: 支持哪些 AI 模型?

A: CLIProxyAPI 支持多种主流 AI 模型,具体取决于你配置的 API Key:

Gemini 系列: gemini-2.5-flash, gemini-2.5-pro, gemini-3-pro 等
Claude 系列: claude-3-5-sonnet, claude-opus-4-5 等
OpenAI 系列: gpt-4, gpt-3.5-turbo 等

完整列表请参考 CLIProxyAPI 文档。

Q7: 可以同时配置 Gemini 和 Claude 吗?

A: 可以。在 config.yaml 中分别配置不同服务的 API Key,CLIProxyAPI 会根据请求的 model 参数自动路由到对应的服务。

Q8: 如何更新到最新版本?

# 1. 进入项目目录
cd CLIProxyAPI

# 2. 拉取最新代码
git pull origin main

# 3. 重新编译
go build -o cli-proxy-api main.go

# 4. 重启服务
# 如果是前台运行,按 Ctrl+C 停止后重新启动
# 如果是后台运行,找到进程并 kill 后重新启动
pkill -f cli-proxy-api
./cli-proxy-api

目录