Codex

Codex là tác tử lập trình của OpenAI. Bạn có thể dùng Codex CLI trong terminal hoặc quản lý dự án và tác vụ trong ứng dụng máy tính. Bằng cách cấu hình nhà cung cấp mô hình tùy chỉnh, Codex có thể dùng điểm vào tương thích OpenAI Responses của AGTCloud.

Mức hỗ trợ gọi công cụ, suy luận, đa tác tử và độ dài ngữ cảnh có thể khác nhau giữa các mô hình. Chọn mô hình mà API Key hiện tại nhìn thấy và hỗ trợ giao thức Responses.

Chuẩn bị

Trước khi bắt đầu, hãy đảm bảo bạn đã:

Chuẩn bị môi trường terminal và dự án cục bộ cần mở;
Đăng ký và đăng nhập AGTCloud;
Tạo token trên trang API Keys;
Sao chép ID mô hình mà token hiện tại có thể dùng và hỗ trợ Responses từ danh mục mô hình.

Cài đặt Codex

Chọn phương thức cài đặt phù hợp với môi trường hiện tại.

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Sau khi cài đặt, mở lại terminal và kiểm tra phiên bản:

codex --version

Cấu hình API Key

Codex đọc API Key từ biến môi trường do Provider tùy chỉnh chỉ định. Hướng dẫn này dùng biến riêng AGTCLOUD_API_KEY để tránh nhầm với Key của OpenAI hoặc nền tảng khác.

Cấu hình tạm thời

Cấu hình dưới đây chỉ có hiệu lực trong phiên terminal hiện tại.

export AGTCLOUD_API_KEY="your-api-key"

Cấu hình lâu dài

Để tự áp dụng mỗi khi mở terminal, ghi biến vào tệp cấu hình shell hoặc biến môi trường người dùng Windows.

Sửa ~/.zshrc và thêm:

export AGTCLOUD_API_KEY="your-api-key"

Sau khi lưu, tải cấu hình:

source ~/.zshrc

Không ghi API Key vào config.toml

config.toml chỉ lưu tên biến môi trường. API Key được lưu dạng văn bản thuần trong cấu hình môi trường cục bộ; chỉ dùng cách này trên thiết bị cá nhân đáng tin cậy.

Cấu hình AGTCloud Provider

Cấu hình cấp người dùng của Codex nằm ở ~/.codex/config.toml. Nếu tệp đã tồn tại, sao lưu trước rồi hợp nhất AGTCloud Provider vào cấu hình hiện có, không ghi đè các thiết lập khác.

mkdir -p ~/.codex

if [[ -f ~/.codex/config.toml ]]; then
    cp ~/.codex/config.toml ~/.codex/config.toml.backup
fi

Thêm vào ~/.codex/config.toml:

model_provider = "agtcloud"
model = "MODEL_ID"

[model_providers.agtcloud]
name = "AGTCloud"
base_url = "https://api.agtcloud.cn/v1"
env_key = "AGTCLOUD_API_KEY"
wire_api = "responses"

Mục cấu hình	Vai trò
`model_provider`	Đổi nhà cung cấp mô hình mặc định sang AGTCloud
`model`	Chỉ định ID mô hình Codex sử dụng
`base_url`	Gửi yêu cầu Responses đến địa chỉ API AGTCloud hiển thị trên trang này
`env_key`	Chỉ định tên biến môi trường lưu API Key
`wire_api`	Chỉ định giao thức OpenAI Responses

Provider phải nằm trong cấu hình cấp người dùng

.codex/config.toml trong dự án có thể lưu thiết lập dự án, nhưng không thể ghi đè model_provider và model_providers. Đặt cấu hình Provider trên trong ~/.codex/config.toml ở thư mục người dùng.

Chọn mô hình

MODEL_ID là giá trị giữ chỗ cần thay thế, không phải tên mô hình thực tế. Sao chép ID mô hình mà API Key hiện tại có thể dùng và hỗ trợ Responses từ danh mục mô hình, rồi thay MODEL_ID trong config.toml.

Trong Codex CLI, dùng /model để xem hoặc chuyển mô hình. Với Provider tùy chỉnh, phạm vi lựa chọn phụ thuộc phiên bản Codex và API Key hiện tại; nếu không thấy mô hình đích, cập nhật trực tiếp model trong config.toml.

Sử dụng Codex CLI

Vào thư mục dự án

cd /path/to/your/project

Khởi chạy Codex

codex

Kiểm tra cấu hình hiện tại

Trong Codex, chạy:

/status

Xác nhận Provider, mô hình và tệp cấu hình hiện tại đúng như dự kiến. Base URL phải là địa chỉ API /v1 hiển thị trên trang này, không có /v1/v1 lặp.

Thử tác vụ chỉ đọc

Trong dự án thử nghiệm có README.md, nhập:

Hãy đọc README.md và tóm tắt mục đích dự án thành ba ý. Không sửa bất kỳ tệp nào.

Nội dung trả về bình thường cho thấy kết nối cơ bản đã được thiết lập. Bước này phát sinh mức sử dụng API thông thường.

Sử dụng Codex App

Khởi động lại App

Sau khi lưu ~/.codex/config.toml và biến môi trường, thoát hoàn toàn Codex App rồi mở lại.

Mở dự án cục bộ

Chuyển sang Codex trong ứng dụng máy tính rồi chọn dự án thử nghiệm không chứa mã nhạy cảm.

Kiểm tra mô hình và xác minh

Xác nhận mô hình hiện tại khớp config.toml, rồi kiểm tra bằng tác vụ chỉ đọc README giống như với CLI.

Cách App tải biến môi trường phụ thuộc phiên bản và cách khởi chạy

Codex App dùng chung cấu hình cục bộ của Codex, nhưng cách ứng dụng máy tính tải biến môi trường shell có thể thay đổi theo phiên bản và hệ điều hành. Nếu CLI dùng được nhưng App không đọc được API Key, khởi động lại hoàn toàn App rồi kiểm tra cấu hình cấp người dùng và biến môi trường.

Câu hỏi thường gặp

Hiện tượng	Kiểm tra trước	Cách xử lý
Không tìm thấy lệnh `codex`	Kết quả cài đặt và `PATH`	Mở lại terminal, chạy `codex --version`; nếu cần, chạy lại lệnh cài đặt chính thức
API Key chưa được tải	`AGTCLOUD_API_KEY` có hiệu lực trong tiến trình hiện tại không	Mở lại terminal hoặc App và tải lại cấu hình môi trường người dùng
Cấu hình Provider không có hiệu lực	Có ghi nhầm vào `.codex/config.toml` cấp dự án không	Chuyển `model_provider` và `model_providers` sang `~/.codex/config.toml`
Đường dẫn yêu cầu có `/v1/v1`	`base_url` có bị nối thêm không	Dùng trực tiếp `https://api.agtcloud.cn/v1` hiển thị trên trang này
Trả về `401`	API Key và biến môi trường	Dùng API Key hợp lệ, xác nhận tên `env_key` khớp
Trả về `403`	Quyền token, quyền mô hình và trạng thái tài khoản	Kiểm tra phạm vi dùng token và mô hình trong bảng điều khiển
Trả về `404`	Base URL, điểm vào Responses và ID mô hình	Kiểm tra `base_url`, sao chép lại ID mô hình mà Key hiện tại dùng được
Mô hình không tồn tại hoặc không khả dụng	Khả năng hiển thị mô hình và hỗ trợ Responses	Sao chép ID đầy đủ từ danh mục mô hình, chọn mô hình mà Key hiện tại có thể gọi
CLI hoạt động nhưng App không đọc cấu hình	Phiên bản App, đường dẫn cấu hình và biến môi trường	Khởi động lại hoàn toàn App; kiểm tra cùng cấu hình cấp người dùng bằng CLI trước
Một số khả năng nâng cao không khả dụng	Khả năng mô hình đích và phạm vi thích ứng hiện tại	Kiểm tra bằng tác vụ chỉ đọc cơ bản trước; khả năng nâng cao dựa trên kết quả gọi thực tế

Nếu chưa xác định được vấn đề, ghi lại thời gian yêu cầu, API Base URL, ID mô hình, trạng thái HTTP và lỗi đã loại thông tin nhạy cảm, rồi xem Lỗi và khắc phục sự cố. Không gửi API Key đầy đủ.

Khuyến nghị bảo mật

Tạo API Key riêng cho Codex để dễ quản lý quyền và vô hiệu hóa thông tin xác thực.
Không ghi Key thật vào config.toml, mã, kho mã, ảnh chụp màn hình, nhật ký hoặc script dùng chung.
Trên thiết bị dùng chung hoặc trong nhóm, ưu tiên quản lý thông tin xác thực của hệ điều hành hoặc cơ chế phân phối khóa tập trung của tổ chức.
Nếu nghi API Key bị lộ, vô hiệu hóa hoặc xóa ngay trong bảng điều khiển rồi tạo Key mới.

Tiếp theo, bạn có thể đọc API Key, Base URL và xác thực, OpenAI Responses và Lỗi và khắc phục sự cố.

Trên trang này