个人技术知识库

6分钟阅读

CLIProxyAPI安装与配置指南

适用版本：CLIProxyAPI v7.2.88。

工具简介

CLIProxyAPI是一个AI模型代理网关，提供统一的API接口接入多个AI服务提供商（OpenAI、Anthropic、Google、DeepSeek等）。

系统要求

  • 操作系统：macOS、Linux、Windows
  • 网络：需要访问各AI提供商API
  • 存储：配置文件、日志文件存储空间

安装方法

1. macOS安装

# 使用Homebrew安装
brew install cliproxyapi
 
# 启动服务
brew services start cliproxyapi

2. Linux安装

Arch Linux (AUR)

# 使用yay
yay -S cli-proxy-api-bin
 
# 使用paru
paru -S cli-proxy-api-bin
 
# 启动服务（systemd用户服务）
systemctl --user start cli-proxy-api
 
# 设置开机自启
systemctl --user enable cli-proxy-api

注意：服务启动前需要配置文件：

mkdir -p ~/.cli-proxy-api
cp /usr/share/doc/cli-proxy-api-bin/config.example.yaml ~/.cli-proxy-api/config.yaml

3. Windows安装

  • 方法一：下载可执行文件

4. Docker部署

Docker 场景需要让进程在容器内监听所有接口，同时仅把端口发布到宿主机回环地址。以下差异只适用于 Docker；非容器部署继续使用后文的 host: "127.0.0.1"。

不发布的 Docker 专用 config.yaml 应包含实际客户端 API key，并使用：

host: "0.0.0.0"
port: 8317
docker run --rm \
  -p 127.0.0.1:8317:8317 \
  -v /path/to/your/config.yaml:/CLIProxyAPI/config.yaml \
  -v /path/to/your/auth-dir:/root/.cli-proxy-api \
  eceasy/cli-proxy-api:latest

5. 源码编译安装

# 克隆仓库
git clone https://github.com/router-for-me/CLIProxyAPI.git
cd CLIProxyAPI
 
# 构建程序
# Linux/macOS
go build -o cli-proxy-api ./cmd/server
 
# Windows
go build -o cli-proxy-api.exe ./cmd/server

基础配置详解

配置文件结构

CLIProxyAPI 使用 YAML 格式配置文件，默认读取当前工作目录的 config.yaml，也可用 cli-proxy-api -config config.yaml 指定。

核心配置项

该公开示例刻意禁用远程监听、远程管理和客户端访问；真实密钥只写入不发布的本地配置。

host: "127.0.0.1"
port: 8317
auth-dir: "~/.cli-proxy-api"
debug: false
logging-to-file: false
usage-statistics-enabled: false
remote-management:
  allow-remote: false
  secret-key: ""
  disable-control-panel: false
proxy-url: ""
request-retry: 3
disable-cooling: false
api-keys: []
ws-auth: true

Gemini API配置

gemini-api-key:
  - api-key: ""
    base-url: "https://generativelanguage.googleapis.com" # 官方或第三方
    headers:
      X-Custom-Header: "custom-value"
    proxy-url: "socks5://proxy.example.com:1080"
  - api-key: "" # 第二个账号

Codex API配置

codex-api-key:
  - api-key: ""
    base-url: "https://www.example.com" # 中转站地址
    proxy-url: "socks5://proxy.example.com:1080"

Claude API配置

claude-api-key:
  - api-key: "" # 官方Key（不填base-url）
  - api-key: ""
    base-url: "https://www.example.com" # 第三方中转
    proxy-url: "socks5://proxy.example.com:1080"
    models:
      - name: "claude-3-5-sonnet-20241022" # 中转商模型名
        alias: "claude-sonnet-latest" # 客户端使用的别名

OpenAI兼容服务

openai-compatibility:
  - name: "openrouter"
    base-url: "https://openrouter.ai/api/v1"
    api-key-entries:
      - api-key: ""
        proxy-url: "socks5://proxy.example.com:1080"
      - api-key: ""
    models:
      - name: "moonshotai/kimi-k2:free" # 供应商模型名
        alias: "kimi-k2" # 客户端别名

完整配置示例（简化版）

host: "127.0.0.1"
port: 8317
auth-dir: "~/.cli-proxy-api"
debug: false
logging-to-file: false
usage-statistics-enabled: false
 
remote-management:
  allow-remote: false
  secret-key: ""
  disable-control-panel: false
 
api-keys: []
 
proxy-url: ""
request-retry: 3
 
disable-cooling: false
gemini-api-key: []
claude-api-key: []
openai-compatibility: []
ws-auth: true

验证安装与配置

# 检查配置文件语法
yamllint ~/.cli-proxy-api/config.yaml
 
# 启动服务测试
cli-proxy-api --config ~/.cli-proxy-api/config.yaml
 
# 测试API访问
curl http://localhost:8317/v1/models \
  -H "Authorization: Bearer your-api-key-1"

集成到OpenClaw

OpenClaw配置示例

在OpenClaw的openclaw.json中添加cliproxyapi provider：

"models": {
  "providers": {
    "cliproxyapi": {
      "baseUrl": "http://localhost:8317/v1",
      "api": "openai-completions",
      "models": [
        {
          "id": "claude-sonnet-4-6",
          "name": "Claude Sonnet 4.6",
          "api": "openai-completions",
          "reasoning": false,
          "input": ["text"],
          "contextWindow": 128000,
          "maxTokens": 8192
        },
        {
          "id": "gemini-3-pro-low",
          "name": "Gemini 3 Pro Low",
          "api": "openai-completions",
          "reasoning": false,
          "input": ["text"],
          "contextWindow": 128000,
          "maxTokens": 8192
        }
      ]
    }
  }
}

模型别名配置

"agents": {
  "defaults": {
    "models": {
      "cliproxyapi/claude-sonnet-4-6": {
        "alias": "claude-sonnet-4-6"
      },
      "cliproxyapi/gemini-3-pro-low": {
        "alias": "gemini-3-pro-low"
      }
    }
  }
}

故障排查

1. 服务无法启动

  • 检查端口8317是否被占用：netstat -tlnp | grep 8317
  • 验证YAML配置文件语法
  • 查看日志文件：tail -f ~/.cli-proxy-api/logs/cli-proxy-api.log

2. API调用失败

  • 验证各AI提供商API Key有效性
  • 检查网络连接和代理配置
  • 测试直接访问AI提供商API

3. 模型不可用

  • 检查CLIProxyAPI配置中的模型名称和别名
  • 验证OpenClaw中的provider配置
  • 查看CLIProxyAPI日志中的错误信息

4. 性能问题

  • 调整request-retry参数
  • 启用多账号轮询（switch-project: true）
  • 检查代理延迟

最佳实践

安全实践

  1. API Key管理：

    • 使用环境变量存储敏感密钥
    • 定期轮换API Key
    • 限制访问IP范围

  2. 访问控制：

    • 为不同客户端分配不同API Key
    • 启用请求日志审计
    • 设置请求频率限制

性能优化

  1. 连接池：调整并发连接数
  2. 缓存策略：启用响应缓存
  3. 负载均衡：配置多账号轮询

监控告警

  1. 健康检查：定期测试API端点
  2. 错误监控：设置错误率告警
  3. 成本控制：监控API使用量

注意事项

  • 首次运行前需要创建配置文件目录
  • 采用 loopback-only 配置时无需开放入站 8317 端口；跨主机访问使用有效证书的 HTTPS 端点或受控隧道
  • 生产环境建议使用Docker或systemd服务管理
  • 定期更新到最新版本获取新功能和修复

文档来源：

关系图谱

反向链接