# Claude Code CLI — Configuration with OmniRoute (Tiếng Việt) 🌐 **Languages:** 🇺🇸 [English](../../../../guides/CLAUDE-CODE-CONFIGURATION.md) · 🇪🇹 [am](../../../am/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇸🇦 [ar](../../../ar/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇦🇿 [az](../../../az/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇧🇬 [bg](../../../bg/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇧🇩 [bn](../../../bn/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇧🇦 [bs](../../../bs/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇨🇿 [cs](../../../cs/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇩🇰 [da](../../../da/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇩🇪 [de](../../../de/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇬🇷 [el](../../../el/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇪🇸 [es](../../../es/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇪🇪 [et](../../../et/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇷 [fa](../../../fa/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇫🇮 [fi](../../../fi/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇫🇷 [fr](../../../fr/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇪 [ga](../../../ga/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇳 [gu](../../../gu/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇳🇬 [ha](../../../ha/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇱 [he](../../../he/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇳 [hi](../../../hi/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇭🇷 [hr](../../../hr/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇭🇺 [hu](../../../hu/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇦🇲 [hy](../../../hy/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇩 [id](../../../id/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇳🇬 [ig](../../../ig/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇹 [it](../../../it/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇯🇵 [ja](../../../ja/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇬🇪 [ka](../../../ka/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇰🇭 [km](../../../km/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇳 [kn](../../../kn/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇰🇷 [ko](../../../ko/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇱🇹 [lt](../../../lt/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇱🇻 [lv](../../../lv/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇳 [ml](../../../ml/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇳 [mr](../../../mr/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇲🇾 [ms](../../../ms/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇲🇹 [mt](../../../mt/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇲🇲 [my](../../../my/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇳🇵 [ne](../../../ne/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇳🇱 [nl](../../../nl/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇳🇴 [no](../../../no/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇳 [or](../../../or/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇳 [pa](../../../pa/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇵🇭 [phi](../../../phi/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇵🇱 [pl](../../../pl/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇵🇹 [pt](../../../pt/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇷🇴 [ro](../../../ro/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇷🇺 [ru](../../../ru/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇱🇰 [si](../../../si/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇸🇰 [sk](../../../sk/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇸🇮 [sl](../../../sl/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇷🇸 [sr](../../../sr/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇸🇪 [sv](../../../sv/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇰🇪 [sw](../../../sw/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇳 [ta](../../../ta/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇳 [te](../../../te/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇹🇭 [th](../../../th/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇹🇷 [tr](../../../tr/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇵🇰 [ur](../../../ur/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇺🇿 [uz](../../../uz/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇳🇬 [yo](../../../yo/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/guides/CLAUDE-CODE-CONFIGURATION.md) --- Trỏ CLI **Claude Code** (`claude`) đến OmniRoute — cục bộ hoặc VPS từ xa — với các cấu hình riêng cho từng mô hình, tương tự như thiết lập Codex. --- ## Bắt đầu nhanh ```bash # Khởi chạy Claude Code với OmniRoute cục bộ (tự động phát hiện ngữ cảnh đang hoạt động) omniroute launch # Với OmniRoute từ xa (sau khi chạy `omniroute connect `, việc này diễn ra tự động) omniroute launch --remote http://192.168.0.15:20128 --api-key oma_live_xxx # Tạo cấu hình riêng cho từng mô hình, sau đó khởi chạy một cấu hình omniroute setup-claude # ghi vào ~/.claude/profiles//settings.json omniroute launch --profile glm52 # Claude Code sử dụng glm/glm-5.2 thông qua OmniRoute ``` --- ## Cách Claude Code kết nối với gateway Claude Code giao tiếp với **Anthropic Messages API** và được trỏ đến một endpoint tùy chỉnh bằng các biến môi trường (không có cờ `--base-url`): | Biến | Mục đích | | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | `ANTHROPIC_BASE_URL` | URL gốc của gateway (Claude Code nối thêm `/v1/messages`). **Không có hậu tố `/v1`.** | | `ANTHROPIC_AUTH_TOKEN` | Được gửi dưới dạng `Authorization: Bearer …` — sử dụng access token / API key OmniRoute của bạn | | `ANTHROPIC_API_KEY` | Phương án thay thế: được gửi dưới dạng `x-api-key`. Nếu cả hai đều được đặt, `ANTHROPIC_AUTH_TOKEN` ưu tiên | | `ANTHROPIC_MODEL` | Buộc sử dụng một mô hình cụ thể (ghi đè lựa chọn mặc định của bộ chọn `/model`) | | `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | `1` → bộ chọn `/model` gốc liệt kê các mô hình `claude*`/`anthropic*` từ `/v1/models` | | `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | Giới hạn số token đầu ra cho mỗi phản hồi (ví dụ: `65536`) | | `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | Ngưỡng token để tự động thu gọn | > Các biến môi trường chỉ được đọc **một lần khi khởi động** — hãy khởi động lại Claude Code sau khi thay đổi chúng. `omniroute launch` thiết lập tất cả các biến này cho bạn: lệnh này phân giải URL cơ sở + token từ ngữ cảnh đang hoạt động (vì vậy, sau khi chạy `omniroute connect ` rồi `omniroute launch`, mọi thứ sẽ tự hoạt động), kiểm tra tình trạng máy chủ và thực thi `claude`. --- ## Bí danh khám phá — hiển thị các mô hình không phải Claude trong bộ chọn `/model` Tính năng khám phá mô hình gateway của Claude Code chỉ liệt kê các id bắt đầu bằng `claude` hoặc `anthropic`, vì vậy khi dùng `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1`, bộ chọn `/model` gốc thường **chỉ** hiển thị các mô hình Claude/Anthropic của OmniRoute — một mô hình `kimi/kimi-k2.6` hoặc `glm/glm-5.2` sẽ không bao giờ xuất hiện, dù vẫn được định tuyến bình thường. OmniRoute có thể sao chép bất kỳ mô hình (và tổ hợp) nào đang bật dưới một id `claude/…` để id đó vượt qua bộ lọc và xuất hiện trong bộ chọn: ``` kimi/kimi-k2.6 → claude/kimi/kimi-k2.6 "Kimi K2.6 (OmniRoute)" glm/glm-5.2 → claude/glm/glm-5.2 "GLM 5.2 (OmniRoute)" → claude/combo/custo-otimizado ``` Khi bạn chọn một trong các mô hình này trong Claude Code, OmniRoute sẽ loại bỏ lớp bao `claude/` để khôi phục id thực trước khi định tuyến — một id `claude/` chính thống (nhà cung cấp Claude OAuth thực tế) luôn được giữ nguyên. **Tính năng này mặc định bị tắt** và được kiểm soát bởi một cơ chế ba cấp (cấp cụ thể nhất được ưu tiên), do đó OmniRoute thông thường sẽ không nhân đôi danh mục đối với các ứng dụng khách không sử dụng Claude Code: | Cấp | Vị trí | | ------------ | ----------------------------------------------------------------------------------------------------------- | | Mô hình | Trang chi tiết nhà cung cấp → nút bật/tắt "Hiển thị trong Claude Code" cho từng mô hình | | Nhà cung cấp | Trang chi tiết nhà cung cấp → nút bật/tắt cấp nhà cung cấp (áp dụng cho tất cả mô hình của nhà cung cấp đó) | | Toàn cục | Cài đặt → Cờ tính năng → `EXPOSE_CC_DISCOVERY_ALIASES` (mặc định tắt) | Biến môi trường `EXPOSE_CC_DISCOVERY_ALIASES` buộc bật cấp toàn cục và được ưu tiên hơn thiết lập ghi đè trên bảng điều khiển (màn hình Cờ tính năng hiển thị ghi chú "đang hoạt động thông qua biến môi trường" khi trường hợp này xảy ra). Các nút bật/tắt cho từng nhà cung cấp và từng mô hình tiếp tục tinh chỉnh từ đó — ví dụ: nếu cấp toàn cục tắt nhưng nhà cung cấp Kimi bật, thì chỉ các mô hình của Kimi được hiển thị. > ⚠️ **Không khớp cửa sổ trên các mô hình không phải Claude.** Claude Code giả định cửa sổ ngữ cảnh > 200K cho mọi id mà nó không nhận diện được (nó không thể đọc cửa sổ thực từ > `/v1/models`). Với mô hình có cửa sổ lớn hơn (ví dụ: 256K của Kimi K2), hãy đặt > `CLAUDE_CODE_AUTO_COMPACT_WINDOW` thành một giá trị thấp hơn cửa sổ thực của mô hình để > tính năng tự động thu gọn không kích hoạt quá sớm. Các cấu hình được tạo ở trên đã > thực hiện điều này cho từng mô hình. --- ## Khối hướng dẫn bắt đầu trên bảng điều khiển Thẻ công cụ Claude (**Dashboard → CLI Code**) hiển thị chính xác đoạn `settings.json` dành cho phiên bản này, bên cạnh nút thông tin về bí danh khám phá, kèm theo nút sao chép: ```jsonc { "env": { "ANTHROPIC_BASE_URL": "http://:20128", "ANTHROPIC_AUTH_TOKEN": "", "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1", }, } ``` URL cơ sở là URL được thẻ phân giải (bao gồm cả giá trị ghi đè tùy chỉnh mà bạn đã nhập), đã được chuẩn hóa — không có hậu tố `/v1`, không có dấu gạch chéo ở cuối. **Khóa không bao giờ được hiển thị**: khối này sử dụng một phần giữ chỗ, vì vậy ảnh chụp màn hình hoặc đoạn mã được dán sẽ không thể làm lộ khóa. Hãy thay thế phần đó bằng khóa của bạn. Thêm `CLAUDE_CODE_AUTO_COMPACT_WINDOW` vào cùng khối `env` cho bất kỳ mô hình nào có cửa sổ ngữ cảnh thực tế không phải là 200K — Claude Code giả định 200K cho mọi id mà nó không nhận dạng được, vì vậy nếu không, tính năng tự động thu gọn sẽ kích hoạt sai thời điểm (xem cảnh báo trong phần trước). Trình tạo đoạn cấu hình cũng chấp nhận giá trị đó, nhờ vậy bên gọi biết cửa sổ của mô hình đích có thể xuất trực tiếp giá trị này. Nguồn: `src/shared/services/claudeCliConfig.ts::buildClaudeDiscoverySettingsSnippet` (trình tạo thuần túy, đã được kiểm thử đơn vị) được hiển thị bởi `ClaudeGatewayOnboardingBlock`. --- ## Hồ sơ (`CLAUDE_CONFIG_DIR`) Claude Code **không có tệp hồ sơ gốc** (không giống `~/.codex/.config.toml` của Codex). Cơ chế tiêu chuẩn là `CLAUDE_CONFIG_DIR` — một thư mục cấu hình riêng cho mỗi hồ sơ, mỗi thư mục có `settings.json`, thông tin xác thực, lịch sử và bộ nhớ đệm riêng. `omniroute setup-claude` lấy danh mục `/v1/models` hiện tại và ghi một hồ sơ cho mỗi mô hình tại `~/.claude/profiles//settings.json`, sử dụng lại **cùng tên như `setup-codex`** (`glm52`, `kimi-k27`, `deepseek-pro`, …): ```jsonc // ~/.claude/profiles/glm52/settings.json { "$schema": "https://json.schemastore.org/claude-code-settings.json", "model": "glm/glm-5.2", "effortLevel": "xhigh", "env": { "ANTHROPIC_BASE_URL": "http://192.168.0.15:20128", "ANTHROPIC_MODEL": "glm/glm-5.2", "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1", "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "190000", }, } ``` > **Token xác thực không bao giờ được ghi vào hồ sơ.** Khởi chạy bằng > `omniroute launch --profile ` (lệnh này chèn `ANTHROPIC_AUTH_TOKEN` từ > ngữ cảnh đang hoạt động), hoặc tự xuất `ANTHROPIC_AUTH_TOKEN` rồi chạy > `CLAUDE_CONFIG_DIR=~/.claude/profiles/ claude`. **Tự động đồng bộ sau khi phát hiện mô hình (tùy chọn bật).** OmniRoute có thể tự động tạo lại các tệp `~/.claude/profiles//settings.json` này bất cứ khi nào thao tác đồng bộ mô hình của nhà cung cấp làm thay đổi danh mục hiện tại — nhờ đó các mô hình mới hoặc được đổi tên sẽ có hồ sơ mà không cần chạy lại lệnh. Tính năng này **mặc định bị tắt**: bật hoặc tắt từ **bảng điều khiển CLI Code** ("Tự động đồng bộ hồ sơ CLI" → Claude Code), hoặc đặt `OMNIROUTE_AUTO_SYNC_CLAUDE_PROFILES=true` (tính năng này cũng tuân theo `CLI_ALLOW_CONFIG_WRITES`, mặc định được bật). Khi được bật, tính năng này chỉ ghi các tệp hồ sơ; nó không bao giờ thay đổi cấu hình Claude đang hoạt động/mặc định, thông tin xác thực hoặc `~/.claude/settings.json`. ### Tạo + sử dụng hồ sơ ```bash # OmniRoute cục bộ omniroute setup-claude # VPS từ xa (nhúng URL của VPS vào mọi hồ sơ) omniroute setup-claude --remote http://192.168.0.15:20128 --api-key oma_live_xxx # Chỉ một số nhà cung cấp omniroute setup-claude --only glm,kimi # Đồng thời ghi hồ sơ cho các nhà cung cấp CLI cục bộ (zcode, auggie, devin-cli-agentic, # codex-app-server) không được phát hiện trên máy này (mặc định bị bỏ qua đối với đích cục bộ) omniroute setup-claude --include-local # Xem trước mà không ghi omniroute setup-claude --dry-run # Khởi chạy một hồ sơ omniroute launch --profile kimi-k27 ``` --- ## Các tầng mô hình (tùy chọn) Claude Code định tuyến đến các tầng năng lực. Ánh xạ từng tầng đến một mô hình OmniRoute thông qua biến môi trường / cài đặt nếu bạn muốn sử dụng các nhà cung cấp khác nhau cho từng tầng: ```bash export ANTHROPIC_DEFAULT_OPUS_MODEL="glm/glm-5.2" export ANTHROPIC_DEFAULT_SONNET_MODEL="kmc/kimi-k2.6" export ANTHROPIC_DEFAULT_HAIKU_MODEL="glm/glm-4.7-flash" ``` Nếu không, một `ANTHROPIC_MODEL` duy nhất (do các hồ sơ thiết lập) sẽ được sử dụng cho mọi thứ. --- ## Chế độ từ xa Sau khi bạn chạy `omniroute connect ` (xem [Chế độ từ xa](./REMOTE-MODE.md)), `omniroute launch` và `omniroute setup-claude` sẽ tự động nhắm đến máy chủ từ xa đó và sử dụng mã thông báo truy cập có phạm vi của máy chủ — không cần cờ bổ sung. Ghi đè cho từng lần gọi bằng `--remote` / `--api-key`. --- ## Khắc phục sự cố **Claude Code bỏ qua cổng kết nối** — hãy xác nhận `ANTHROPIC_BASE_URL` **không có `/v1`** và khởi động lại `claude` (biến môi trường chỉ được đọc một lần khi khởi động). `omniroute launch` sẽ xử lý việc này cho bạn. **Trình chọn `/model` trống / thiếu các mô hình của cổng kết nối** — yêu cầu Claude Code v2.1.219+ và `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1`. Chỉ các ID mô hình `claude*` / `anthropic*` xuất hiện trong trình chọn; buộc sử dụng bất kỳ mô hình nào khác bằng `ANTHROPIC_MODEL=` (đây là cách các hồ sơ hoạt động). **`400 Ambiguous model 'claude-…'`** — Claude Code luôn gửi các ID mô hình **không có tiền tố** (ví dụ: `claude-opus-4-8`), vì vậy khi cả nhà cung cấp Claude Code (`cc/…`) và Claude (`claude/…`) đều được kết nối, ID không có tiền tố sẽ khớp với hai tuyến và OmniRoute từ chối phỏng đoán. Khắc phục theo một trong hai cách: cố định một ID có tiền tố bằng `ANTHROPIC_MODEL=cc/claude-opus-4-8`, hoặc bật **Ưu tiên Claude Code cho các mô hình Claude không có tiền tố** — nút bật/tắt trên trang của nhà cung cấp Claude, hoặc `OMNIROUTE_PREFER_CLAUDE_CODE_FOR_UNPREFIXED_CLAUDE_MODELS=true` (mặc định tắt; xem [Môi trường](../reference/ENVIRONMENT.md)) — thao tác này sẽ định tuyến các ID `claude-*` không có tiền tố đến Claude Code. Tiền tố nhà cung cấp rõ ràng luôn được ưu tiên. **Lỗi xác thực** — hồ sơ không chứa mã thông báo. Sử dụng `omniroute launch --profile` (để chèn mã thông báo) hoặc xuất `ANTHROPIC_AUTH_TOKEN`. **Các hồ sơ không được cách ly** — mỗi hồ sơ là một `CLAUDE_CONFIG_DIR` riêng biệt; hãy xác minh `echo $CLAUDE_CONFIG_DIR` bên trong phiên trỏ đến `~/.claude/profiles/`.