API Hop

Tài liệu

Tài liệu API Hop

Tích hợp Codex

>-

Codex gọi mô hình qua giao thức OpenAI Responses. Cấu hình nhà cung cấp mô hình bằng URL cơ sở tương thích OpenAI trên trang này.

text
Codex base_url: https://api.apihop.ai/openai

Điều kiện trước

Chuẩn bị khóa API API Hop hợp lệ trước. Khóa sẽ được ghi vào thư mục cấu hình Codex cục bộ. Không đưa vào kho mã, nhật ký hoặc ảnh chụp màn hình.

Codex thường lưu tệp cấu hình tại:

  • macOS / Linux: ~/.codex/
  • Windows: %userprofile%\.codex\

Nếu thư mục hoặc tệp cấu hình chưa tồn tại, tạo trước:

bash
mkdir -p ~/.codex
touch ~/.codex/config.toml

Với Windows CMD:

bat
mkdir %userprofile%\.codex
type nul > %userprofile%\.codex\config.toml

Sao lưu cấu hình

Nếu từng dùng Codex, sao lưu cấu hình hiện tại trước:

bash
cp ~/.codex/config.toml ~/.codex/config.toml.bak
cp ~/.codex/auth.json ~/.codex/auth.json.bak

Cập nhật config.toml

Mở ~/.codex/config.toml, rồi thêm hoặc cập nhật cấu hình này:

toml
model_provider = "apihop"
model = "gpt-5.4"
review_model = "gpt-5.4"
model_reasoning_effort = "high"
disable_response_storage = true
network_access = "enabled"

[model_providers.apihop]
name = "API Hop"
base_url = "https://api.apihop.ai/openai"
wire_api = "responses"
requires_openai_auth = true
supports_websockets = true
websocket_connect_timeout_ms = 15000

[features]
responses_websockets = true

Quy tắc base_url là: URL cơ sở API công khai trên trang này + /openai.

Nếu config.toml đã chứa [marketplaces.*], [plugins.*] hoặc cài đặt công cụ khác, giữ chúng và chỉ thêm hoặc cập nhật cài đặt nhà cung cấp mô hình Codex bên trên.

Chế độ WebSocket

Khi bật supports_websockets = true và responses_websockets = true, Codex dùng điểm cuối Responses WebSocket dưới đây:

text
https://api.apihop.ai/openai/responses

Nếu URL cơ sở API dùng https://, Codex dùng kết nối wss:// tương ứng.

Chế độ WebSocket này là cầu nối Responses qua WebSocket riêng cho Codex:

  • Hỗ trợ response.create
  • Hỗ trợ response.cancel
  • Trả response.completed
  • Cũng giữ sự kiện tương thích response.processed

response.cancelled xác nhận yêu cầu hủy cục bộ. Nó không xác nhận hoàn tiền thượng nguồn. Yêu cầu có kết quả thượng nguồn chưa rõ vẫn giữ chỗ cho đến khi lượng sử dụng hoặc thất bại được xác minh.

Đây không phải OpenAI Realtime API. Không hỗ trợ session.update, conversation.item.*, input_audio_buffer.*, truyền luồng âm thanh, tin nhắn nhị phân hoặc lớp bao Realtime.

Nếu proxy mạng, cổng doanh nghiệp hoặc phiên bản Codex cũ không thể thiết lập kết nối WebSocket, tạm chuyển sang:

toml
[model_providers.apihop]
supports_websockets = false

[features]
responses_websockets = false

Codex sau đó dùng HTTP POST https://api.apihop.ai/openai/responses dự phòng. Compact là năng lực riêng: năm mô hình GPT hiện được liệt kê chưa có kênh Compact được kiểm chứng. Chuyển chế độ HTTP/WebSocket không bật nén ngữ cảnh. Bắt đầu hội thoại mới trước khi vượt giới hạn ngữ cảnh mô hình; không phụ thuộc nén ngữ cảnh dài tự động với các tuyến này.

Ghi khóa API

Thay YOUR_APIHOP_API_KEY bằng khóa API API Hop của bạn:

bash
echo '{"OPENAI_API_KEY":"YOUR_APIHOP_API_KEY"}' > ~/.codex/auth.json

Với Windows CMD:

bat
echo {"OPENAI_API_KEY":"YOUR_APIHOP_API_KEY"} > %userprofile%\.codex\auth.json

Khởi động lại và kiểm thử

Lưu cấu hình, thoát hoàn toàn Codex, rồi mở lại.

Bạn có thể kiểm thử CLI bằng:

bash
codex "Reply in one sentence whether the current model is available."

Với tiện ích VS Code hoặc ứng dụng máy tính, thoát hoàn toàn ứng dụng, mở lại, rồi bắt đầu hội thoại thông thường.

Khắc phục sự cố

  • base_url phải là URL cơ sở API công khai trên trang này cộng /openai.
  • wire_api phải là responses; không đổi thành chat.
  • Lỗi Compact không khả dụng nghĩa là chưa có kênh Compact được kiểm chứng; đổi ngưỡng token cục bộ không thể bật nó.
  • API Hop hỗ trợ cả HTTP Responses và Codex Responses WebSocket. Mặc định giữ supports_websockets = true và responses_websockets = true. Nếu phiên bản Codex hoặc proxy mạng không dùng được WebSocket, tạm đặt supports_websockets = false để dùng HTTP dự phòng.
  • auth.json phải là JSON hợp lệ và tên khóa phải là OPENAI_API_KEY.
  • Nếu nhận 401 hoặc invalid key, xác nhận khóa API hợp lệ và không bị khóa cục bộ cũ ghi đè.
  • Nếu mô hình không khả dụng, kiểm tra GET https://api.apihop.ai/v1/models và đặt model, review_model thành mô hình GPT hiển thị. Ví dụ mặc định dùng gpt-5.4; gpt-5.3-codex và gpt-5.6-luna hiện chưa bật.
  • Thoát hoàn toàn và mở lại Codex sau khi đổi cấu hình. Chỉ đóng cửa sổ có thể không nạp lại auth.json.
  • POST https://api.apihop.ai/openai/responses: điểm cuối tương thích Responses của API Hop được khuyến nghị.
  • POST https://api.apihop.ai/openai/responses/compact: yêu cầu kênh Compact được bật rõ ràng; nếu không trả 503 trước khi giữ chỗ. Kênh được hỗ trợ trả response.compaction.
  • WS /openai/responses: điểm cuối tương thích Responses WebSocket. Hỗ trợ response.create, response.cancel, trả response.completed và giữ sự kiện tương thích response.processed.
  • WS /openai/responses/compact: dùng cùng kiểm tra năng lực Compact và điểm cuối. Chỉ bắt tay WebSocket không chứng minh mô hình được hỗ trợ.