> For the complete documentation index, see [llms.txt](https://docs.avis.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avis.net/vi/tich-hop/coding/codex.md). # Codex CLI ## Hướng dẫn tích hợp Codex CLI Hướng dẫn này trình bày cách kết nối [Codex CLI](https://github.com/openai/codex), agent lập trình chính thức của OpenAI chạy trên terminal, với API tương thích OpenAI của AVIS. ### Codex CLI là gì Codex CLI là agent lập trình mã nguồn mở chạy trên terminal, có thể đọc và sửa tệp cũng như thực thi lệnh shell. Công cụ dùng Responses API (và Chat Completions) của OpenAI, nên có thể kết nối với AVIS qua giao diện tương thích OpenAI. Endpoint `/responses` của AVIS dành cho Codex CLI/Desktop. ### 1) Cài đặt Codex CLI ```bash # npm npm install -g @openai/codex # Homebrew brew install --cask codex # macOS / Linux (curl) curl -fsSL https://chatgpt.com/codex/install.sh | sh # Windows PowerShell powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex" ``` Kiểm tra: ```bash which codex ``` ### 2) Lấy AVIS API key Xem phần Xác thực — đăng nhập tại [avis.net](https://avis.net), vào **Settings → API Keys** và tạo một key. ### 3) Cấu hình AVIS làm nhà cung cấp mô hình Đặt key trong shell của bạn: ```bash export AVIS_API_KEY="" ``` Chỉnh sửa `~/.codex/config.toml`: ```toml model_provider = "avis" model = "claude-sonnet-5" [model_providers.avis] name = "AVIS" base_url = "https://api.avis.net/api/openai/v1" env_key = "AVIS_API_KEY" wire_api = "responses" ``` Ghi chú: * `env_key` là tên biến môi trường mà Codex đọc key — Codex gửi nó dưới dạng `Authorization: Bearer `, mà AVIS chấp nhận như một cách thay thế cho `x-api-key` (xem phần Xác thực). * `wire_api = "responses"` nhắm tới endpoint `/responses` của AVIS — cấu trúc gốc của Codex CLI/Desktop. Dùng `wire_api = "chat"` để nhắm tới `/chat/completions` nếu bạn thực sự cần ngữ nghĩa của Chat Completions; với chính Codex CLI, hãy dùng `"responses"`. * `model_provider` phải khớp với tên bảng trong `[model_providers.*]` (ở đây là `avis`) — Codex định tuyến mọi lệnh gọi qua nhà cung cấp mà key cấp cao nhất này chỉ định. * Bạn không thể đặt tên nhà cung cấp tùy chỉnh là `openai`, `ollama` hoặc `lmstudio` — các id này được dành riêng cho các nhà cung cấp tích hợp sẵn của Codex. ### 4) Chọn mô hình Truy vấn danh mục trực tiếp để lấy chính xác các ID hiện tại — giao diện này dùng id chuẩn dạng phẳng của AVIS (không có tiền tố `anthropic/`/`openai/`): ```bash curl https://api.avis.net/api/openai/v1/models \ -H "x-api-key: $AVIS_API_KEY" | jq '.data[].id' ``` Đặt `model` (cấp cao nhất, §3) thành một trong các giá trị này, ví dụ `claude-sonnet-5`, `claude-opus-5`, `gpt-5.5`. ### 5) Chạy Codex CLI ```bash cd your-project codex ``` Ở lần chạy đầu tiên trong một thư mục mới, Codex sẽ hỏi bạn có tin tưởng dự án hay không — hãy chấp nhận để Codex được phép đọc/sửa/thực thi trong thư mục đó. Để phê duyệt trước một dự án mà không cần tương tác, hãy thêm vào `config.toml`: ```toml [projects."/absolute/path/to/your/project"] trust_level = "trusted" ``` ### 6) Khắc phục sự cố * `warning: Model metadata for '' not found. Defaulting to fallback metadata; this can degrade performance and cause issues.` (kèm lỗi `failed to refresh available models` tương ứng trong log) * Codex cố gắng lấy danh mục mô hình từ nhà cung cấp để biết context window/khả năng suy luận của mô hình được cấu hình, và mong đợi cấu trúc `{"models": [...]}`. `GET /models` của AVIS lại trả về cấu trúc chuẩn OpenAI `{"object": "list", "data": [...]}`, nên Codex dùng metadata chung thay thế. * **Điều này không chặn request** — việc tạo văn bản vẫn hoạt động (xem Danh sách kiểm tra tối thiểu bên dưới) — nhưng hành vi về mức suy luận/giới hạn ngữ cảnh có thể kém chính xác hơn so với nhà cung cấp mà Codex có đầy đủ metadata. * `401 Unauthorized` * `AVIS_API_KEY` chưa được export trong shell mà Codex được khởi chạy — `env_key` sẽ thành rỗng nếu biến không được đặt ở đó. * AVIS key không hợp lệ hoặc đã bị thu hồi — kiểm tra trực tiếp: `curl -H "x-api-key: $AVIS_API_KEY" https://api.avis.net/api/openai/v1/models`. * `400` / request bị từ chối ngay lập tức * `wire_api` không khớp với ý định của bạn — `"responses"` và `"chat"` gọi tới các endpoint AVIS khác nhau (`/responses` so với `/chat/completions`) với cấu trúc request khác nhau; đặt sai `wire_api` so với endpoint bạn muốn sẽ thất bại ở mức cấu trúc request, không phải ở bước xác thực. * `404` / không tìm thấy mô hình * Giá trị `model` không khớp chính xác với danh mục của AVIS (id phẳng, không có tiền tố) — kiểm tra lại với `GET /api/openai/v1/models` (§4). * `403` với key hợp lệ * Số dư tài khoản đã hết — xem phần Lỗi. * Codex vẫn gọi OpenAI API thật thay vì AVIS * `model_provider` ở cấp cao nhất của `config.toml` phải bằng tên bảng trong `[model_providers.*]` — gõ sai ở đây sẽ âm thầm quay về nhà cung cấp `openai` tích hợp sẵn của Codex thay vì báo lỗi. ### 7) Danh sách kiểm tra tối thiểu từ đầu đến cuối 1. Đã tạo AVIS API key (§2) và export thành `AVIS_API_KEY`. 2. `~/.codex/config.toml` có `model_provider = "avis"`, một khối `[model_providers.avis]` tương ứng với `base_url`/`env_key`/`wire_api`, và một `model` đã được xác nhận với danh mục của AVIS (§3–4). 3. Dự án đã được tin tưởng (§5). 4. `codex` khởi động và một tin nhắn trả về kết quả từ mô hình chạy qua AVIS. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.avis.net/vi/tich-hop/coding/codex.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.