Hướng dẫn cấu hình Codex CLI với Beeknoee

4:19

Codex CLI là gì?

Codex CLI là AI coding agent của OpenAI — chạy trực tiếp trong terminal, hỗ trợ viết code, debug, chạy lệnh và tự động hoàn thành task. Beeknoee Platform hỗ trợ Codex CLI thông qua endpoint OpenAI-compatible.

💡 Khi dùng Codex CLI qua Beeknoee, bạn có thể dùng các model GPT/Codex của OpenAI với giá tối ưu và thanh toán bằng VND.

⚠️ Quan trọng (cập nhật 2026): Codex CLI đã bỏ giao thức chat/completions cho custom provider — nay bắt buộc dùng Responses API (wire_api = "responses"). Beeknoee đã hỗ trợ endpoint /v1/responses nên Codex chạy bình thường.

Yêu cầu

• Node.js 22+ (nodejs.org)
• API Key từ Beeknoee Platform

📌 Bước 1: Cài đặt Codex CLI

npm install -g @openai/codex

Kiểm tra cài đặt thành công:

codex --version

📌 Bước 2: Tạo API Key

1. Truy cập https://platform.beeknoee.com/api-keys
2. Đăng nhập bằng tài khoản Google
3. Nhấn "Tạo API Key"
4. Copy API Key (dạng sk-bee-xxxx...)

⚠️ API key chỉ hiển thị 24 giờ đầu — copy và lưu ngay!

🚀 Bước 3: Cấu hình qua Quick Setup (khuyên dùng)

Cách nhanh nhất — hệ thống tự sinh lệnh cài đặt cho bạn:

1. Vào trang API Keys

2. Chọn API Key bạn muốn dùng → nhấn ⚙️ Cấu hình API Key

3. Trong dialog, chuyển sang tab "Quick Setup"

4. Chọn tab Codex CLI

5. Chọn hệ điều hành — Windows hoặc macOS / Linux

6. Chọn Model Mapping (tuỳ chọn):

   • Small (Fast): Model nhẹ, nhanh — dùng cho task đơn giản (ví dụ: gpt-5.4-nano)
   • Medium (Default): Model mặc định — cân bằng tốc độ/chất lượng (ví dụ: gpt-5.4)
   • Large (Powerful): Model mạnh nhất — dùng cho task phức tạp (ví dụ: gpt-5.5)

   💡 Chỉ hiện các model OpenAI. Nếu không biết chọn gì, giữ mặc định là ổn!

7. Copy lệnh — nhấn nút Copy bên cạnh khung lệnh

8. Mở PowerShell (Windows) hoặc Terminal (macOS/Linux)

9. Dán lệnh và nhấn Enter

10. Sau khi cài xong, gõ codex để bắt đầu

Script tự động thực hiện:

• ✅ Thêm [model_providers.beeknoee] vào ~/.codex/config.toml — chỉ thêm, không đụng provider / profile / [mcp_servers] sẵn có, không đổi model mặc định của bạn
• ✅ Tự đọc codex --version rồi ghi profile đúng kiểu cho bản đó (xem mục dưới)
• ✅ Ghi danh mục model riêng ra ~/.codex/beeknoee-models.json — không đụng models.json của bạn
• ✅ Đặt stream_idle_timeout_ms + stream_max_retries để request suy nghĩ lâu không bị cắt
• ✅ Sao lưu bản gốc vào ~/.codex/.beeknoee-backups/original/ (chụp 1 lần, không bị đè)

Cài trên máy đã có config.toml → chạy bằng codex --profile beeknoee. Cài trên máy chưa có file nào → chạy codex là được.

💡 Còn 5 công cụ nữa trong khối Công cụ khác: Xem trước, Kiểm tra máy, Kiểm chứng cấu hình, Gỡ riêng cấu hình Beeknoee, Gỡ cài đặt (khôi phục toàn bộ) — xem Quick Setup.

⚠️ Codex 0.134 đổi cách khai báo profile

Đây là thay đổi hay làm hỏng hướng dẫn cũ trên mạng:

Từ 0.134, Codex không còn đọc bảng [profiles.*] trong config.toml nữa. Nếu bạn chép hướng dẫn cũ, codex --profile beeknoee sẽ chạy nhưng không hề dùng cấu hình Beeknoee — im lặng, không báo lỗi.

Kiểm tra bản của bạn:

codex --version

Quick Setup tự xử lý chuyện này. Chỉ khi cấu hình tay bạn mới cần để ý.

🛠️ Hoặc cấu hình thủ công (~/.codex/config.toml)

Nếu không dùng Quick Setup, tự thêm Beeknoee như một custom model provider (dùng Responses API).

Phần 1 — provider, thêm vào cuối ~/.codex/config.toml (chung cho mọi phiên bản):

[model_providers.beeknoee]
name = "Beeknoee"
base_url = "https://platform.beeknoee.com/v1"
env_key = "BEEKNOEE_API_KEY"      # tên biến môi trường chứa API key
wire_api = "responses"            # BẮT BUỘC — Codex 2026 không còn nhận "chat"
stream_idle_timeout_ms = 600000   # model nghĩ lâu vẫn không bị cắt stream
stream_max_retries = 5

Phần 2 — profile, chọn đúng kiểu theo phiên bản:

Codex ≥ 0.134 → tạo file mới ~/.codex/beeknoee.config.toml:

model = "<model-id>"              # copy Model ID từ trang Models
model_provider = "beeknoee"

Codex < 0.134 → thêm tiếp vào config.toml:

[profiles.beeknoee]
model = "<model-id>"
model_provider = "beeknoee"

Phần 3 — set biến môi trường chứa key (Codex đọc key từ biến này, không hardcode vào file):

# Linux/macOS
export BEEKNOEE_API_KEY="sk-bee-YOUR_API_KEY"

# Windows PowerShell
$env:BEEKNOEE_API_KEY = "sk-bee-YOUR_API_KEY"

⚠️ ID provider không được trùng các id dành riêng của Codex (openai, ollama, lmstudio) — dùng beeknoee như trên.

📌 Bước 4: Kiểm tra kết nối

cd /path/to/your/project
codex --profile beeknoee

Codex CLI sẽ tự kết nối đến Beeknoee và sẵn sàng nhận lệnh.

💡 Không muốn gõ --profile mỗi lần? Đặt biến CODEX_PROFILE=beeknoee trong shell profile của bạn.

📌 Chọn model

Codex CLI sử dụng model mapping qua config.toml. Nếu bạn đã cấu hình qua Quick Setup, model đã được set sẵn.

Models khuyên dùng với Codex CLI:

💡 Model ID chính xác và giá realtime xem tại trang Models trên Dashboard.

💡 Nếu bạn đã kết nối email qua BeeSynapse Integrations (Codex), các model GPT Codex có thể dùng miễn phí qua free quota!

🆓 Models miễn phí qua BeeSynapse

Khi đã kết nối email tại trang BeeSynapse Integrations, hệ thống tự động ưu tiên free quota:

Danh sách model free thay đổi theo quota nhà cung cấp — xem chính xác tại trang BeeSynapse Integrations. Bạn không cần thay đổi gì — Beeknoee tự route qua free quota trước, hết quota mới trừ VND.

🗑️ Gỡ cài đặt

Nếu muốn gỡ cấu hình Beeknoee và quay lại dùng OpenAI trực tiếp:

1. Vào trang API Keys → ⚙️ Cấu hình API Key → Quick Setup
2. Chọn tab Codex CLI
3. Trong khối Công cụ khác, bấm Copy ở dòng "Gỡ cài đặt (khôi phục toàn bộ)" — hoặc dòng "Gỡ riêng cấu hình Beeknoee" nếu chỉ muốn bỏ Beeknoee mà giữ nguyên phần còn lại
4. Dán vào terminal và chạy

Script khôi phục từ bản chụp gốc ở ~/.codex/.beeknoee-backups/original/ — đúng trạng thái trước khi cài Beeknoee.

💡 Chỉ muốn bỏ phần Beeknoee mà giữ nguyên provider/model bạn thêm sau đó? Dùng nút Gỡ riêng cấu hình Beeknoee — xem Quick Setup.

Xử lý lỗi thường gặp

"Invalid API key" hoặc "authentication_error"

Codex đọc key theo env_key khai trong config.toml, không phải OPENAI_API_KEY. Kiểm tra biến đó đã có giá trị:

# Linux/macOS
echo $BEEKNOEE_API_KEY

# Windows PowerShell
echo $env:BEEKNOEE_API_KEY

• Trống → set lại biến, hoặc chạy Quick Setup (cách này nhúng key thẳng vào provider nên không cần biến môi trường)
• Có giá trị nhưng vẫn lỗi → key sai/bị thu hồi, kiểm tra tại API Keys; key phải bắt đầu bằng sk-bee-

"Could not connect"

• Kiểm tra base_url trong [model_providers.beeknoee] đúng là https://platform.beeknoee.com/v1
• Kiểm tra kết nối internet

Chạy codex --profile beeknoee nhưng vẫn dùng provider cũ

Bạn đang ở Codex ≥ 0.134 mà profile lại khai bằng bảng [profiles.beeknoee] trong config.toml — bản này không đọc bảng đó nữa. Chuyển sang file riêng ~/.codex/beeknoee.config.toml (xem mục Codex 0.134 đổi cách khai báo profile), hoặc chạy lại Quick Setup để script tự ghi đúng kiểu.

"Model not found"

• Kiểm tra Model ID tại trang Các Mô Hình AI
• Đảm bảo dùng đúng providerModelId (copy chính xác từ trang Models, không phải tên hiển thị)

"API Error 524" (model chậm / reasoning)

Model Claude và các model reasoning có thể suy nghĩ >120s. Nếu gặp Error 524, hãy đảm bảo gọi ở chế độ streaming (stream: true) — token trả về liên tục nên không bị Cloudflare cắt ở 120s. Xem Error Handling.

Giải thích cơ chế

Codex CLI → POST /v1/responses (Responses API của OpenAI)
                    ↓
              Beeknoee Backend
                    ↓
              Resolve key → chọn provider → gọi API → billing
                    ↓
              Trả response (Responses API) → Codex CLI

Codex CLI (bản 2026) gửi request theo Responses API (/v1/responses), Beeknoee nhận và xử lý qua hệ thống AI Proxy, rồi trả kết quả lại theo đúng định dạng Responses API.

So sánh với dùng OpenAI trực tiếp

HOÀN TẤT! 🎉

Cần hỗ trợ thêm? Sử dụng Support Chat (góc dưới phải trên platform) hoặc liên hệ qua email.

Xem thêm hướng dẫn tích hợp khác

• Claude Code — Anthropic AI coding CLI
• OpenCode — AI coding CLI (OpenAI-compatible)
• Cursor — AI-first code editor
• Cline — VS Code AI agent
• Continue — VS Code/JetBrains extension
• Windsurf — AI IDE với Cascade Flow
• Zed — Code editor Rust siêu nhanh
• Kilo Code — VS Code AI coding agent
• Aider — AI pair programming CLI