跳至主要內容

LiteLLM Proxy CLI

lite CLI 是一個命令列工具，用於管理您的 LiteLLM proxy 伺服器，並透過它執行程式碼代理程式。它可管理模型、憑證、 API 金鑰、團隊與使用者，執行對 proxy 的 chat 和 HTTP 請求， 將靜態儲存的憑證加密進行遷移，並啟動程式碼代理程式（Claude Code、 Codex、OpenCode），讓其 LLM 流量經由 proxy 路由。

功能您可以做什麼
程式碼代理程式透過 proxy 執行 Claude Code、Codex 或 OpenCode
模型管理列出、新增、更新與刪除模型
憑證管理管理提供者憑證
金鑰管理產生、列出、刪除與匯入 API 金鑰
團隊管理列出團隊、列出可加入的團隊、將您的金鑰指派給團隊
使用者管理建立、列出與刪除使用者
聊天補全執行 chat completions
HTTP Requests對 proxy 伺服器發出自訂 HTTP 請求
Encryption Migration將靜態儲存的憑證重新加密為 AES-256-GCM

快速開始​

  1. 安裝 CLI

lite 用戶端是一個輕量的筆電安裝：它會連到 LiteLLM proxy，並透過它執行您的程式碼代理程式，不會帶入 proxy 伺服器執行時環境。單行安裝程式只需要 curl；若找不到 uv 會先建立，並讓 uv 為您提供相容的 Python：

   curl -fsSL https://raw.githubusercontent.com/BerriAI/litellm/main/scripts/install-cli.sh | sh

已經有 uv，而且想自行操作嗎？直接安裝套件：

uv tool install 'litellm[cli]'

任何這些都會提供 lite 指令。從 litellm[proxy] 安裝的 proxy 伺服器也會一併提供，但該額外套件不包含 keyring，因此其憑證會保留在檔案中，而不是您的作業系統金鑰圈中。請先在終端機中輸入：

   lite
  1. 設定環境變數
   export LITELLM_PROXY_URL=http://localhost:4000
   export LITELLM_PROXY_API_KEY=sk-your-key

(請替換為您的實際 proxy URL 和 API 金鑰)

  1. 發出第一個請求（列出模型）
   lite models list

如果 CLI 設定正確，您應該會看到可用模型清單或表格輸出。

  1. 疑難排解
  • 如果看到錯誤，請檢查您的環境變數與 proxy 伺服器狀態。

使用 CLI 進行驗證​

您可以使用 CLI 來驗證到 LiteLLM Gateway。若您想為大量開發人員提供自助式存取 LiteLLM Gateway，這很有幫助。

資訊

如需深入指南，請參閱 CLI 驗證。

先決條件​

Beta 功能 - 必要環境變數

CLI SSO 驗證目前仍在 beta 階段。您必須在啟動 LiteLLM Proxy 時設定此環境變數：

export EXPERIMENTAL_UI_LOGIN="True"
litellm --config config.yaml

或者將它加入您的 proxy 啟動指令：

EXPERIMENTAL_UI_LOGIN="True" litellm --config config.yaml

步驟​

  1. 設定 proxy URL
   export LITELLM_PROXY_URL=http://localhost:4000

(請替換為您的實際 proxy URL)

  1. 登入
   lite login

這會開啟瀏覽器視窗進行驗證。如果您已將 LiteLLM Proxy 連接到您的 SSO 提供者，您可以使用 SSO 憑證登入。登入後，您可以使用 CLI 向 LiteLLM Gateway 發出請求。

若要改用 OAuth authorization code 與 PKCE 透過系統瀏覽器登入，請執行 lite login --pkce。該憑證會使用 refresh token 自動更新，而 lite auth print-token 會將其交給 Claude Code、OpenCode，或任何相容 OpenAI 的用戶端。請參閱 使用 PKCE 透過瀏覽器登入

  1. 測試您的驗證
   lite models list

這會列出您可用的所有模型。

透過 proxy 執行程式碼代理程式​

啟動程式碼代理程式，讓其所有 LLM 流量都經由您的 LiteLLM proxy 路由。每個支援的代理程式都有自己的指令，因此除了代理程式名稱之外不需要記住其他內容：

lite claude
lite codex
lite opencode

代理程式名稱之後的任何內容都會原封不動地傳遞給代理程式，因此它自己的旗標仍可正常運作：

lite claude --resume
lite codex exec "summarize the repo"

每個指令都會解析您的 LiteLLM 金鑰（若未儲存且您在終端機中，則透過 SSO 登入；否則會讀取 LITELLM_PROXY_API_KEY 或 --api-key），先向 proxy 檢查金鑰，讓錯誤憑證立即失敗，而不是等到代理程式內部才出錯，接著匯出代理程式會讀取的環境變數，最後以代理程式程序取代自身。

這些變數會依代理程式而定。Claude Code 會取得 ANTHROPIC_BASE_URL（proxy 根位址，因此會附加 /v1/messages）與 ANTHROPIC_AUTH_TOKEN，並清除任何殘留的 ANTHROPIC_API_KEY，讓 proxy 權杖優先。Codex 和 OpenCode 會取得 OPENAI_BASE_URL（proxy 加上 /v1）與 OPENAI_API_KEY。Codex 不會理會 OPENAI_BASE_URL，因此還會透過傳入 -c 設定覆寫的自訂提供者，另外指向 proxy（HTTP/SSE Responses 傳輸，因為 proxy 不支援 Responses WebSocket 協定）。

--skip-verify 會略過啟動前的金鑰檢查，這在離線或使用非標準驗證時很有幫助。它屬於 wrapper，因此請把它放在代理程式自己的旗標之前：

lite claude --skip-verify --resume

若要固定模型，請傳入代理程式自己的模型旗標（lite claude --model my-proxy-model 或 lite codex -m my-proxy-model），或匯出代理程式會讀取的變數（Claude Code 為 ANTHROPIC_MODEL / ANTHROPIC_SMALL_FAST_MODEL）；wrapper 會保留您已設定的任何內容。代理程式所要求的模型必須存在於 proxy 上，因為請求會送到 proxy 的 /v1/messages（Anthropic）或 /v1/chat/completions 與 /v1/responses（OpenAI）端點。

lite login 憑證​

由 lite login 發行的權杖是一個短效、每個工作階段各自獨立的代理程式憑證，而不是受管理的虛擬金鑰。它的範圍限定於您驗證時使用的使用者與團隊，會繼承該使用者與團隊的模型和預算，並且在 proxy 上的強制方式與同一團隊上的虛擬金鑰完全相同（防護欄、路由、記錄、支出）。支出會計入共用的團隊與使用者預算，因此執行多個代理程式（或多次登入）不會讓每個工作階段都有自己的預算；它們都會從同一份團隊與使用者額度中扣除，而且沒有獨立的每工作階段上限。

此憑證刻意設計為短效（預設 24 小時，可透過 LITELLM_CLI_JWT_EXPIRATION_HOURS 設定）；再次執行 lite login 即可重新整理，且也會重新讀取您最新的團隊與使用者設定。它不會出現在 Keys UI 中，也無法在工作階段中途輪替或撤銷，而 lite claude、lite codex 與 lite opencode 可在預設部署上與它搭配使用。若您需要一個會顯示在 Keys UI 中、可輪替且長效的金鑰，請在儀表板中建立專用的虛擬金鑰，並改用 --api-key 或 LITELLM_PROXY_API_KEY 傳入。

lite login 會將憑證保存在您的作業系統金鑰圈中（macOS Keychain、Windows Credential Manager，或 Linux Secret Service），其服務為 litellm-cli，帳戶為 credential。只有非機密部分會寫入 ~/.litellm/token.json：gateway URL、您的 user id、電子郵件與角色、auth 標頭名稱，以及登入時間戳記。該檔案會在 0600 內的 0700 目錄中建立。存取 keychain 需要 keyring 套件，而它隨 cli 額外安裝包一同提供，因此若您想使用 keychain 儲存，請以 pip install 'litellm[cli]' 安裝，而不要只用單純的 pip install litellm 或 pip install 'litellm[proxy]'。透過 litellm.get_litellm_gateway_api_key() 讀回憑證的程式碼也需要 keyring，原因相同：沒有它，呼叫將無法看到 keychain 項目並會回傳 None，即使 lite login 已儲存了一份

沒有 keychain 的機器，例如無頭 Linux 主機，則會把憑證保存在同一個僅限擁有者的檔案中；缺少 keyring 的安裝，以及將 LITELLM_CLI_DISABLE_KEYRING 設為 1、true、yes 或 on 的 shell 也會如此，這會完全關閉 keychain 儲存。lite login 會在任一情況下印出憑證的存放位置。較舊的 lite 以純文字寫入 token.json 的憑證仍可通過驗證：下一個讀取它的指令會將其移入 keychain，並從檔案中移除

來自 lite login --pkce 的憑證也會附帶 refresh token：CLI 會在下次使用時更新金鑰，lite auth print-token 會將目前的金鑰交給其他工具，而 lite logout 會在 proxy 上撤銷 refresh token。每個更新後的金鑰都會像前一個一樣存入 keychain，購得它的 refresh token 也一樣。請參閱 使用 PKCE 透過瀏覽器登入

當您在登入時向某個團隊進行驗證，或之後想把已儲存的金鑰移到其他團隊時，請使用 lite teams assign-key（請參閱 團隊管理）。使用下列方式檢視或清除已儲存的憑證：

lite whoami             # show the authenticated user and the token age
lite auth print-token   # print the current key, renewing a --pkce credential first when needed
lite logout             # clear the keychain entry and the token file, and revoke a --pkce refresh token

lite logout 會清除兩個儲存區。當 keychain 拒絕釋出該項目，或無法連線進行檢查時，它會向您發出警告並告訴您該怎麼做，而不是回報已乾淨登出

主要指令​

模型管理​

  • 列出、新增、更新、取得與刪除 proxy 上的模型。

  • 範例：

    lite models list
    lite models add gpt-5.6-terra \
      --param api_key=sk-123 \
      --param max_tokens=2048
    lite models update <model-id> -p temperature=0.7
    lite models delete <model-id>

    使用的 API（OpenAPI）

憑證管理​

  • 列出、建立、取得與刪除 LLM 提供者的憑證。

  • 範例：

    lite credentials list
    lite credentials create azure-prod \
      --info='{"custom_llm_provider": "azure"}' \
      --values='{"api_key": "sk-123", "api_base": "https://prod.azure.openai.com"}'
    lite credentials get azure-cred
    lite credentials delete azure-cred

    使用的 API（OpenAPI）

金鑰管理​

  • 列出、產生、刪除並匯入 API 金鑰。若要查找單一金鑰，請依 --key-alias 或 --key-hash 篩選 lite keys list。
  • 範例：
  lite keys list
  lite keys generate \
    --models=gpt-5.6-terra \
    --spend=100 \
    --duration=24h \
    --key-alias=my-key
  lite keys list --key-alias my-key
  lite keys delete --keys sk-key1,sk-key2 --key-aliases alias1,alias2

lite keys import 會將其他 LiteLLM 執行個體中的金鑰複製到此執行個體。加入 --dry-run 可在不寫入的情況下預覽，加入 --created-since（YYYY-MM-DD 或 YYYY-MM-DD_HH:MM）可依建立日期限制匯入範圍：

  lite keys import \
    --source-base-url https://old-proxy.example.com \
    --source-api-key sk-source-admin \
    --created-since 2026-01-01

使用的 API（OpenAPI）

使用者管理​

  • 列出、建立、取得資訊與刪除使用者。

  • 範例：

    lite users list
    lite users create \
      --email=user@example.com \
      --role=internal_user \
      --alias="Alice" \
      --team=team1 \
      --max-budget=100.0
    lite users get --id <user-id>
    lite users delete <user-id>

    使用的 API（OpenAPI）

團隊管理​

  • 列出您所屬的團隊、列出可加入的團隊，並將您目前的 CLI 金鑰指派給團隊。

  • 範例：

    lite teams list
    lite teams available
    lite teams assign-key --team-id team123

    不使用 lite teams assign-key 執行 --team-id 時，系統會提示您以互動方式選取團隊。

    使用的 API（OpenAPI）

聊天完成​

  • 在 proxy 伺服器上以模型開始互動式串流聊天工作階段。省略模型即可互動式選取。
  • 範例：
  lite chat gpt-5.6-terra
  lite chat gpt-5.6-terra --temperature 0.9 --system "You are a helpful coding assistant"

使用的 API（OpenAPI）

一般 HTTP 請求​

  • 直接向 proxy 伺服器發出 HTTP 請求。

  • 範例：

    lite http request \
      POST /chat/completions \
      --json '{"model": "gpt-5.6-terra", "messages": [{"role": "user", "content": "Hello"}]}'

    所有 API（OpenAPI）

加密遷移​

  • 將靜態儲存的憑證重新加密為 AES-256-GCM (v2:gcm:) 格式。這是一項管理作業；請先以 general_settings.encryption_algorithm: aes-256-gcm 啟動 proxy。此遷移具有冪等性且可續跑，因此即使中途中斷，重新執行也很安全。

  • 範例：

    lite encryption migrate --check    # read-only residual scan, no writes
    lite encryption migrate --dry-run  # run the walkers without writing changes
    lite encryption migrate            # perform the migration

    --check 會回報仍有多少舊版值；殘留值為 0 代表所有內容都已轉換為新格式。

環境變數​

  • LITELLM_PROXY_URL: proxy 伺服器的基礎 URL
  • LITELLM_PROXY_API_KEY: 用於驗證的 API 金鑰

範例​

  1. 列出所有模型：
   lite models list
  1. 新增模型：
   lite models add gpt-5.6-terra \
     --param api_key=sk-123 \
     --param max_tokens=2048
  1. 建立憑證：
   lite credentials create azure-prod \
     --info='{"custom_llm_provider": "azure"}' \
     --values='{"api_key": "sk-123", "api_base": "https://prod.azure.openai.com"}'

  1. 產生 API 金鑰：

    lite keys generate \
      --models=gpt-5.6-terra \
      --spend=100 \
      --duration=24h \
      --key-alias=my-key

  2. 互動式聊天：

   lite chat gpt-5.6-terra \
     --system "You are a helpful coding assistant"
  1. 自訂 HTTP 請求：
   lite http request \
     POST /chat/completions \
     --json '{"model": "gpt-5.6-terra", "messages": [{"role": "user", "content": "Hello"}]}'

錯誤處理​

CLI 會顯示以下情況的錯誤訊息：

  • 伺服器無法存取
  • 驗證失敗
  • 參數或 JSON 無效
  • 模型／憑證不存在
  • 任何其他作業失敗

請使用 --debug 旗標取得詳細除錯輸出。

如需完整的命令參考與進階用法，請參閱 CLI README。

LiteLLM Enterprise
為正式環境打造的 SSO/SAML、稽核記錄、支出追蹤、多團隊管理與防護欄。
深入瞭解 →