Hướng dẫn cài đặt CLIProxyAPI chi tiết: macOS, Linux, Docker, build source

Nếu bạn muốn dùng CLI model (Gemini CLI, Codex, Claude Code…) thông qua một endpoint thống nhất kiểu OpenAI-compatible, CLIProxyAPI là lựa chọn đáng thử. Bài này là hướng dẫn cài đặt chi tiết theo 4 cách (macOS, Linux, Docker, build from source), kèm checklist cấu hình và test API để chạy ổn định trong môi trường dev/team nhỏ.

CLIProxyAPI là gì và dùng khi nào?

CLIProxyAPI là một service đóng vai trò proxy, cung cấp interface tương thích OpenAI/Gemini/Claude/Codex cho các client/SDK. Điểm mạnh là gom nhiều nguồn model và tài khoản vào một lớp API trung gian để route request, hỗ trợ streaming, tools/function calling, và một số cơ chế load balancing theo tài khoản.

Bạn đang dùng nhiều CLI provider nhưng muốn chuẩn hóa endpoint.
Bạn muốn giữ luồng OAuth/API key ở 1 nơi thay vì mỗi app tự cấu hình riêng.
Bạn cần đổi provider/model mà ít sửa code ở client.

Prerequisites

Máy macOS/Linux/Windows hoặc host chạy Docker.
Quyền chạy service nền (brew services/systemd/container).
Có sẵn config file cho CLIProxyAPI (theo mẫu của project).
Cổng mặc định thường dùng: 8317.

Tip: Nếu chạy production, đặt reverse proxy (Nginx/Caddy) phía trước, giới hạn IP và bật auth/ACL. Tránh expose trực tiếp ra Internet khi chưa có lớp bảo vệ.

Cách 1: Cài trên macOS bằng Homebrew

brew install cliproxyapi
brew services start cliproxyapi

Khi chạy qua brew services, đường dẫn config mặc định là:

Apple Silicon: /opt/homebrew/etc/cliproxyapi.conf
Intel: /usr/local/etc/cliproxyapi.conf

Nếu bạn muốn dùng file chuẩn ở ~/.cli-proxy-api/config.yaml, có thể symlink:

brew services stop cliproxyapi
mv "$(brew --prefix)/etc/cliproxyapi.conf" "$(brew --prefix)/etc/cliproxyapi.conf.bak"
ln -s ~/.cli-proxy-api/config.yaml "$(brew --prefix)/etc/cliproxyapi.conf"
brew services start cliproxyapi

Cách 2: Cài trên Linux

Project có one-click installer script. Trước khi chạy, nên review script để kiểm soát rủi ro supply-chain.

curl -fsSL https://raw.githubusercontent.com/brokechubb/cliproxyapi-installer/refs/heads/master/cliproxyapi-installer | bash

Với Arch Linux (AUR):

# yay
yay -S cli-proxy-api-bin

# hoặc paru
paru -S cli-proxy-api-bin

Sau khi cài, quản lý service bằng systemd user unit:

systemctl --user start cli-proxy-api
systemctl --user enable cli-proxy-api

Nếu thiếu config file, tạo từ mẫu:

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

Cách 3: Chạy bằng Docker (nhanh và sạch môi trường)

docker run --rm -p 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

Trong production, bạn nên chuyển sang docker compose, mount volume cố định cho auth/config và đặt restart policy:

services:
  cliproxyapi:
    image: eceasy/cli-proxy-api:latest
    ports:
      - "8317:8317"
    volumes:
      - ./config.yaml:/CLIProxyAPI/config.yaml:ro
      - ./auth:/root/.cli-proxy-api
    restart: unless-stopped

Cách 4: Build from source

git clone https://github.com/router-for-me/CLIProxyAPI.git
cd CLIProxyAPI
go build -o cli-proxy-api ./cmd/server
./cli-proxy-api

Windows:

go build -o cli-proxy-api.exe ./cmd/server

Smoke test sau cài đặt

Sau khi service chạy, test nhanh endpoint (tùy route bạn cấu hình theo OpenAI/Gemini/Claude compatible path):

curl -s http://127.0.0.1:8317/v1/models | jq

curl -s http://127.0.0.1:8317/v1/chat/completions   -H "Content-Type: application/json"   -d '{
    "model": "your-model-alias",
    "messages": [{"role":"user","content":"hello"}],
    "stream": false
  }' | jq

Nếu không dùng route /v1/..., hãy test đúng provider path theo docs (/api/provider/{provider}/...).

Troubleshooting nhanh

Service chạy nhưng request 401/403: kiểm tra OAuth session/token và config auth-dir mount đúng chưa.
Model not found: kiểm tra model alias trong config, tránh trùng alias giữa nhiều backend.
Port conflict: đổi port publish hoặc stop service cũ đang giữ 8317.
Sau reboot mất đăng nhập: mount persistent volume cho ~/.cli-proxy-api.
Lỗi route: dùng đúng protocol path cho backend family (messages/chat/model-scoped).

Security checklist trước khi public cho team

Không expose thẳng service ra public Internet khi chưa có reverse proxy + ACL.
Giới hạn truy cập theo IP/VPN/Tailscale.
Tách môi trường dev/staging/prod bằng config riêng.
Rotate token/session định kỳ, backup thư mục auth an toàn.
Bật log monitoring để phát hiện request bất thường.

Kết luận

CLIProxyAPI phù hợp cho use case cần một lớp API trung gian để chuẩn hóa nhiều CLI model provider. Nếu bạn cần triển khai nhanh: bắt đầu bằng Docker. Nếu cần chạy ổn định lâu dài trên máy cá nhân macOS: Homebrew service là lựa chọn gọn nhất. Quan trọng nhất là quản lý config/auth-dir cẩn thận và khóa truy cập ngay từ đầu.

Nguồn tham khảo

GitHub: https://github.com/router-for-me/CLIProxyAPI
Quick Start: https://help.router-for.me/introduction/quick-start
Docs tổng: https://help.router-for.me/

Codex (OpenAI via OAuth): cấu hình auth và verify nhanh

Với luồng OpenAI Codex qua OAuth, bạn nên tách rõ phần xác thực khỏi traffic runtime để dễ debug. Sau khi login thành công, kiểm tra file/session auth đã được lưu trong thư mục auth-dir mà CLIProxyAPI đang mount.

Đảm bảo thư mục auth được mount persistent (không dùng tmpfs cho production).
Sau khi OAuth thành công, restart service 1 lần để chắc route nạp session mới.
Map model alias rõ ràng (ví dụ codex/gpt-5-codex) để client gọi nhất quán.

# Kiểm tra endpoint models
curl -s http://127.0.0.1:8317/v1/models | jq

# Test chat completion với alias Codex đã map
curl -s http://127.0.0.1:8317/v1/chat/completions   -H "Content-Type: application/json"   -d '{
    "model": "codex",
    "messages": [{"role":"user","content":"Write a hello world in Go"}],
    "stream": false
  }' | jq

Nếu gặp 401/403 sau một thời gian chạy, thường là session OAuth hết hạn hoặc auth-dir bị ghi đè khi redeploy container. Cách xử lý an toàn là re-auth, kiểm tra quyền ghi của volume và tránh xoá thủ công thư mục session khi service đang chạy.