Duy NghiệnBy
Share
AI & AUTOMATIONSELF HOSTING

Biến gói thuê bao AI (Gemini/Claude) thành API “không giới hạn” với CLIProxyAPI

3 views0

Trong kỷ nguyên Generative AI, chúng ta thường đứng trước một sự lựa chọn khó khăn: trả phí “đắt đỏ” theo từng token sử dụng qua API chính thức (Pay-per-token), hoặc mua gói thuê bao cố định (như Claude Pro, Gemini Advanced) nhưng bị giới hạn trong giao diện Chat UI.

Vậy nếu có một cách để kết hợp cả hai? Hãy tưởng tượng bạn có thể sử dụng sức mạnh của Claude 4.5 Sonnet hay Gemini 3 Pro trong các ứng dụng tự động hóa (n8n, coding agent) nhưng lại tận dụng được hạn mức rộng rãi của tài khoản cá nhân thay vì đốt tiền vào API Key.

Đó chính xác là bài toán mà CLIProxyAPI giải quyết.

CLIProxyAPI là gì?

CLIProxyAPI là một máy chủ proxy trung gian (middleware), đóng vai trò “cầu nối” kỹ thuật. Nó hoạt động bằng cách bao bọc (wrap) các công cụ dòng lệnh (CLI) độc quyền của Google, Anthropic và OpenAI, sau đó phơi bày chúng dưới dạng các API Endpoints chuẩn OpenAI.

Nói cách khác, các ứng dụng của bạn (VS Code, n8n, Factory Droid) sẽ nghĩ rằng chúng đang nói chuyện với OpenAI API, nhưng thực tế CLIProxyAPI đang xử lý và chuyển tiếp yêu cầu đó thông qua gói thuê bao cá nhân của bạn.

Cơ chế “Arbitrage” (Kinh doanh chênh lệch) hoạt động như thế nào?

Hiểu kiến trúc của CLIProxyAPI là chìa khóa để vận hành nó an toàn. Hệ thống không dùng API Key truyền thống của nhà cung cấp, mà sử dụng cơ chế Man-in-the-Middle (MITM) hợp pháp:

  1. Đánh chặn (Interception): Proxy nhận yêu cầu từ ứng dụng của bạn (ví dụ: yêu cầu chat từ n8n). Nó sẽ loại bỏ “API Key giả” mà bạn cấu hình trong ứng dụng.
  2. Tiêm Xác thực (Auth Injection): Proxy tìm kiếm OAuth Token (Access & Refresh Token) mà bạn đã đăng nhập trước đó trong hệ thống, và tiêm nó vào tiêu đề yêu cầu.
  3. Chuyển đổi Giao thức: Nó gửi yêu cầu đến Google/Anthropic dưới danh nghĩa là công cụ CLI chính chủ (như gemini-cli hay claude-code). Vì các CLI này thường đi kèm gói thuê bao người dùng, bạn tránh được chi phí API doanh nghiệp.
  4. Phản hồi: Kết quả trả về (thường là SSE stream) được đóng gói lại thành chuẩn OpenAI JSON để ứng dụng của bạn hiểu được.

Hướng dẫn cài đặt nhanh

Cách 1: Dùng Docker (Khuyên dùng cho Server/Homelab)

Đây là cách ổn định nhất để chạy 24/7 và tích hợp vào n8n.

File docker-compose.yml tối ưu:

services:
  cli-proxy-api:
    image: eceasy/cli-proxy-api:latest
    container_name: cli-proxy-api
    pull_policy: always
    restart: unless-stopped
    ports:
      - "8317:8317"   # Cổng API chính (tương thích OpenAI)
      - "8085:8085"   # Cổng Web UI (nếu bật)
      - "54545:54545" # Cổng Callback bắt buộc để login OAuth
    volumes:
      # Mount file cấu hình để chỉnh sửa dễ dàng
      - ./config.yaml:/CLIProxyAPI/config.yaml
      
      # QUAN TRỌNG: Lưu trữ token đăng nhập. 
      # Nếu không có dòng này, bạn sẽ mất quyền truy cập mỗi khi restart container
      - ./auths:/root/.cli-proxy-api
      
      # Lưu log để debug nếu cần
      - ./logs:/CLIProxyAPI/logs
    environment:
      - TZ=Asia/Ho_Chi_Minh

Lưu ý trước khi chạy:

  1. Tạo trước một file config.yaml rỗng hoặc copy từ mẫu config này và để cùng thư mục với file docker-compose.
  2. Chạy lệnh:
    docker-compose up -d
    1. Sau đó, vào bên trong container để đăng nhập:
    # Login bằng Google account
docker exec -it cli-proxy-api ./CLIProxyAPI -login

# hoặc với Claude Code
docker exec -it cli-proxy-api ./CLIProxyAPI -claude-login

# Login to Antigravity using OAuth
docker exec -it cli-proxy-api ./CLIProxyAPI -antigravity-login

# Login to Codex using OAuth
docker exec -it cli-proxy-api ./CLIProxyAPI -codex-login
    
# Login to iFlow using OAuth
docker exec -it cli-proxy-api ./CLIProxyAPI -iflow-login

# Don't open browser automatically for OAuth
docker exec -it cli-proxy-api ./CLIProxyAPI -no-browser

# Project ID (Gemini only, not required)
docker exec -it cli-proxy-api ./CLIProxyAPI -project_id string

# Login to Qwen using OAuth
docker exec -it cli-proxy-api ./CLIProxyAPI -qwen-login

# Import Vertex service account key JSON file
docker exec -it cli-proxy-api ./CLIProxyAPI -vertex-import string

    Khi bạn đăng nhập vào CLIProxyAPI bằng tài khoản Google cá nhân để tận dụng gói miễn phí, bạn cần tạo Google Cloud Project. Dưới đây là cấu hình chính xác bạn cần thực hiện trên Google Cloud Console:

    Bước 1. API cần bật (Quan trọng)

    Để sử dụng được các model Gemini (như Gemini 1.5 Pro/Flash) qua API, bạn bắt buộc phải bật API sau trong Project của mình:

    • Tên API: Google Generative Language API
    • Tại sao cần?: Đây là API nền tảng cho dịch vụ “Google AI Studio” và các model Gemini miễn phí. Nếu không bật, các yêu cầu gửi đến sẽ bị chặn ngay lập tức.
    • Cách bật:
      1. Vào Google Cloud Console.
      2. Chọn Project bạn vừa tạo.
      3. Vào mục APIs & Services > Library.
      4. Tìm kiếm từ khóa generative language và nhấn Enable.

    Bước 2. Thiết lập OAuth Consent Screen (Màn hình xác thực)

    Để CLIProxyAPI có thể đăng nhập thay mặt bạn vào Project này, bạn cần cấu hình màn hình xác thực OAuth:

    • User Type: Chọn External (Bên ngoài).
      • Lưu ý: Vì project đang ở chế độ “Testing”, bạn cần thêm địa chỉ email của chính mình vào danh sách Test users để có thể đăng nhập được.
    • Scopes (Phạm vi truy cập): Không cần thêm scope đặc biệt nào nếu chỉ dùng cơ bản, nhưng nếu công cụ yêu cầu, thường sẽ là .../auth/generative-language.retriever hoặc openid.

    Bước 3. Tạo OAuth Client ID (Để lấy Token)

    Sau khi bật API và cấu hình màn hình xác thực, bạn cần tạo thông tin xác thực để CLIProxyAPI sử dụng:

    1. Vào APIs & Services > Credentials.
    2. Nhấn Create Credentials > OAuth client ID.
    3. Application type: Chọn Desktop app (Ứng dụng máy tính).
      • Lý do: CLIProxyAPI chạy trên terminal/server, không phải là website có tên miền công khai, nên loại “Desktop app” là phù hợp nhất để xử lý redirect về localhost.
    4. Kết quả: Bạn sẽ nhận được Client ID và Client Secret.

    Cách 2: Package Manager (Mac/Windows)

    Dành cho người dùng chạy trực tiếp trên máy cá nhân:

    • macOS:
    brew install cliproxyapi
    • Windows:
    winget install -e --id LuisPater.CLIProxyAPI

    Quy trình đăng nhập:

    • Chạy lệnh:
      # Login với Google account
./CLIProxyAPI -login

# hoặc với Claude Code
./CLIProxyAPI -claude-login
      1. Hệ thống tạo một server tạm tại http://localhost:54545.
      2. Bạn đăng nhập trên trình duyệt, token sẽ tự động được lưu vào thư mục auths.
      Mẹo cho VPS (Headless Server):
      Nếu cài trên VPS không có giao diện, bạn cần dùng SSH Tunneling để forward cổng 54545 về máy cá nhân mới có thể xác thực được (ssh -L 54545:127.0.0.1:54545 user@vps-ip).

      Cấu hình hệ thống chuyên sâu (config.yaml)

      Tệp config.yaml là “bộ não” điều khiển hành vi của CLIProxyAPI. Một sai sót nhỏ trong cú pháp YAML (như thụt đầu dòng sai) có thể khiến dịch vụ không khởi động. Dưới đây là phân tích chi tiết từng khối cấu hình dựa trên các tài liệu tham khảo.   

      1 Cấu hình mạng và bảo mật cơ bản

      # Cổng lắng nghe dịch vụ
port: 8317

# Cấu hình TLS (HTTPS)
# Chỉ bật khi bạn có chứng chỉ SSL hợp lệ và cần bảo mật đường truyền nội bộ
tls:
  enable: false
  cert: "/path/to/cert.pem"
  key: "/path/to/key.pem"

# Quản lý từ xa (Remote Management)
remote-management:
  # Cho phép truy cập API quản lý từ IP khác localhost hay không?
  # KHUYẾN NGHỊ: Đặt là false trừ khi bạn hiểu rõ rủi ro.
  allow-remote: false 
  # Khóa bí mật bắt buộc nếu allow-remote: true
  # Nếu để trống, API quản lý sẽ bị vô hiệu hóa hoàn toàn.
  secret-key: "YourSuperSecretManagementKey"

      Phân tích An ninh: Tham số allow-remote là một vectơ tấn công tiềm năng. Nếu đặt là true mà không có secret-key mạnh, kẻ tấn công có thể truy cập vào bảng điều khiển quản lý của proxy, xem log, hoặc thậm chí thay đổi cấu hình mapping mô hình. Luôn giữ allow-remote: false nếu proxy chỉ được sử dụng bởi các dịch vụ trên cùng một máy chủ (như n8n chạy cùng Docker network).   

      Bạn muốn giao diện dễ dùng nhất thì nên bật tùy chọn allow-remote: true trong file cấu hình lúc này bạn chỉ cần truy cập http://localhost:8317/management.html là có giao diện để quản lý rồi

      2 Định nghĩa khóa client và lưu trữ token

      # Thư mục lưu trữ OAuth Token
# Dấu ngã (~) đại diện cho thư mục home của người dùng chạy tiến trình
auth-dir: "~/.cli-proxy-api"

# Danh sách các API Key để bảo vệ Proxy này
# Client (ví dụ: Cursor, n8n) phải gửi header "Authorization: Bearer my-secure-client-key"
api-keys:
  - "my-secure-client-key"
  - "team-member-key"

      Cơ chế api-keys: Đây không phải là API Key của Google hay Anthropic. Đây là lớp bảo vệ do bạn tự tạo ra cho proxy của mình. Khi bạn cấu hình n8n kết nối đến CLIProxyAPI, bạn sẽ điền my-secure-client-key vào trường API Key của n8n. Proxy sẽ xác thực khóa này trước, sau đó mới dùng OAuth Token của nó để nói chuyện với Google.   

      3 Quản lý hạn ngạch (Quota) và tự động chuyển đổi (Failover)

      Một tính năng nâng cao là khả năng xử lý lỗi khi vượt quá hạn ngạch sử dụng (Rate Limit).

      quota-exceeded:
  # Tự động chuyển sang dự án Google Cloud/Tài khoản khác nếu dự án hiện tại hết quota
  switch-project: true
  
  # Tự động hạ cấp xuống mô hình Preview nếu mô hình chính thức bị giới hạn
  # Ví dụ: gemini-1.5-pro -> gemini-1.5-pro-preview
  switch-preview-model: true

      Ý nghĩa: Tính năng này biến CLIProxyAPI thành một bộ cân bằng tải (Load Balancer) thông minh. Đối với các tác vụ chạy hàng loạt (batch processing) trong n8n, việc bật switch-project và cung cấp nhiều tài khoản đăng nhập khác nhau cho phép hệ thống duy trì hoạt động liên tục mà không bị gián đoạn bởi các giới hạn API của tài khoản miễn phí.   

      4 Mapping Mô hình (Model Aliasing)

      Đây là tính năng giúp CLIProxyAPI tương thích với mọi phần mềm.

      models:
  # Kịch bản: Client (VD: ứng dụng cũ) chỉ hỗ trợ chọn "gpt-4" trong menu
  # Giải pháp: Map "gpt-4" thành "gemini-2.5-pro"
  - name: "gemini-2.5-pro"  # Mô hình thực tế sẽ chạy
    alias: "gpt-4"          # Tên mà client gửi lên

  # Kịch bản: Client yêu cầu Claude 3 Opus, nhưng bạn muốn dùng Sonnet cho tiết kiệm/nhanh
  - name: "claude-3-5-sonnet-20241022"
    alias: "claude-3-opus"

      Việc cấu hình này giúp người dùng “đánh lừa” các ứng dụng khách khe khắt, buộc chúng sử dụng các mô hình mạnh mẽ hơn hoặc rẻ hơn mà không cần sửa mã nguồn của ứng dụng đó.

      Tích hợp vào quy trình làm việc (workflows)

      1. Cấu hình JSON cho n8n (Xử lý Multimodal/Hình ảnh)

      Vấn đề lớn nhất khi dùng n8n với CLIProxyAPI là Node OpenAI mặc định của n8n thường gửi URL ảnh công khai, trong khi Proxy này yêu cầu dữ liệu ảnh dạng Base64.

      Để giải quyết, chúng ta sẽ không dùng Node OpenAI, mà dùng Node HTTP Request kết hợp với một chút Javascript để xử lý ảnh.

      Bước 1: Node “Code” (Chuyển đổi Binary sang Base64)

      Sau khi bạn dùng node “Read Binary File” hoặc “Telegram Trigger” để lấy ảnh, hãy nối nó vào một Node Code (ngôn ngữ JavaScript) với nội dung sau:

      // Node này trích xuất dữ liệu binary và chuẩn bị chuỗi Base64
const items = $input.all();

return items.map(item => {
  // Giả sử dữ liệu binary nằm ở field tên là 'data' (mặc định của n8n)
  const binaryData = item.binary.data; 
  
  return {
    json: {
      // Trong n8n, item.binary.data.data chính là chuỗi Base64
      base64_image: binaryData.data 
    }
  };
});

      Mục đích là lấy chuỗi mã hóa của bức ảnh để chuẩn bị nhúng vào JSON.

      Bước 2: Node “HTTP Request” (Gửi yêu cầu tới Proxy)

      Đây là thay thế cho Node OpenAI. Cấu hình node này như sau:

      • Method: POST
      • URL: http://cli-proxy-api:8317/v1/chat/completions
        • Lưu ý: Nếu n8n chạy cùng Docker network thì dùng tên service cli-proxy-api, nếu chạy khác nơi thì dùng IP máy chủ của bạn.
      • Authentication:Generic Credential Type -> Header Auth.
        • Name: Authorization
        • Value: Bearer <api-key-cua-ban> (Key bạn tự đặt trong config.yaml phần api-keys).
      • Body Content Type: JSON
      • Body Parameters (Quan trọng nhất):Copy đoạn JSON dưới đây vào phần Expression của Body:
      {
  "model": "gemini-3-pro-preview",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Hãy phân tích chi tiết nội dung trong bức ảnh này."
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "data:image/jpeg;base64,{{ $json.base64_image }}"
          }
        }
      ]
    }
  ],
  "stream": false
}

      Giải thích JSON:

      • "model": "gemini-3-pro-preview": Gọi đúng tên mô hình bạn muốn dùng.
      • data:image/jpeg;base64,{{ $json.base64_image }}: Đây là cú pháp chuẩn để gửi ảnh trực tiếp trong payload JSON mà không cần upload ảnh lên internet. Biến {{ $json.base64_image }} lấy từ kết quả của Node Code ở Bước 1.

      Bổ sung:

      Hiện tại cho dù dùng AI model nào thì bạn cũng phải sử dụng OpenAI và các node của OpenAI để cấu hình nhé, vì chỉ cái này hỗ trợ giao thức mà tác giả dự án đang khai thác.

      Nếu n8n bạn lưu trữ ở VPS tức ngoài mạng LAN bạn cần đưa CLI Proxy API lên domain để kết nối (có thể dùng Cloudflare Tunnels). Hoặc nếu truy cập trong LAN mà máy cài n8n và cài Proxy khác nhau thì cũng cần nhập chính xác IP của máy chủ cài proxy vào bước Base URL nhé.

      2. Coding Assistant (Cursor, VS Code, Factory Droid)

      Bạn có thể dùng các mô hình mạnh nhất như Claude Sonnet 4.5 hay Gemini 3 Pro để code mà không lo về giá.

      • Base URL: http://localhost:8317/v1
      • API Key: Điền bất kỳ (hoặc key bạn set trong config.yaml).
      • Model: Nhập tên mô hình (ví dụ gemini-3-pro-preview). Nếu phần mềm không cho nhập tên, hãy dùng tính năng Mapping (Alias) trong config.yaml để map gpt-5 thành gemini-3-pro-preview.

      Các vấn đề thường gặp & khắc phục

      LỗiNguyên nhân & cách sửa
      HTTP 401 / Token UnavailableToken hết hạn. Hãy chạy lại lệnh login (--claude-login).
      Model not found (404)Tên mô hình sai. Kiểm tra lại config.yaml và đảm bảo alias khớp với yêu cầu từ client.
      Address in useCổng 8317 bị chiếm. Đổi port trong config và docker compose.

      CLIProxyAPI là một công cụ mạnh mẽ dành cho những ai muốn khai thác tối đa giá trị của các gói thuê bao AI. Nó đòi hỏi một chút kiến thức kỹ thuật để thiết lập (Docker, OAuth), nhưng lợi ích kinh tế và hiệu năng mang lại là rất lớn.

      Tuy nhiên, hãy nhớ rằng đây là một dự án cộng đồng (Community-driven). Các nhà cung cấp như Google hay Anthropic có thể thay đổi cơ chế bất cứ lúc nào, vì vậy việc theo dõi cập nhật từ kho lưu trữ router-for-me là rất quan trọng.

      Tham khảo: leolion

      Duy Nghiện
      Hãy làm khán giả, đừng làm nhân vật chính :)

      You may also like

      Nhận thông báo qua email
      Nhận thông báo cho
      guest

      0 Bình luận
      Mới nhất
      Cũ nhất Nhiều like nhất
      Phản hồi nội tuyến
      Xem tất cả bình luận