Chuẩn bị trước khi cấu hình
Kimi K3.1 Pro là mô hình có thể kết nối trực tiếp với Claude Code và Codex nhờ hỗ trợ các giao thức Anthropic Messages, OpenAI Responses và OpenAI Chat Completions. Cách cấu hình Kimi K3.1 Pro phù hợp nếu bạn đã có khóa API Moonshot và muốn dùng mô hình này ngay trong công cụ lập trình mình quen thuộc, không cần proxy chuyển đổi giao thức.
Điểm cần nhớ là Claude Code và Codex dùng hai giao thức khác nhau: Claude Code kết nối qua Anthropic Messages tại https://api.moonshot.ai/anthropic, còn Codex dùng Responses tại https://api.moonshot.ai/v1. Cả hai đều nhận mã mô hình kimi-k3.1-pro. Khóa API nên được giữ trong biến môi trường, không ghi trực tiếp vào tệp cấu hình.
Mô hình luôn suy luận; không có công tắc tắt. Có thể điều chỉnh mức suy luận bằng trường reasoning_effort cấp cao nhất với các giá trị low, high hoặc max; mặc định là max. Các tham số lấy mẫu như temperature được cố định, nên đừng mang nguyên thiết lập tinh chỉnh từ một mô hình khác sang.
Thiết lập Kimi trong Claude Code
Claude Code đọc cấu hình từ khối env trong ~/.claude/settings.json. Thêm các biến dưới đây vào khối này; thay YOUR_KIMI_API_KEY bằng khóa API của bạn. Nếu đã khai báo biến cùng tên trong shell, giá trị trong tệp cài đặt sẽ được ưu tiên.
- ANTHROPIC_BASE_URL=https://api.moonshot.ai/anthropic
- ANTHROPIC_AUTH_TOKEN=YOUR_KIMI_API_KEY
- ANTHROPIC_MODEL=kimi-k3.1-pro
- ANTHROPIC_DEFAULT_OPUS_MODEL=kimi-k3.1-pro
- ANTHROPIC_DEFAULT_SONNET_MODEL=kimi-k3.1-pro
- ANTHROPIC_DEFAULT_HAIKU_MODEL=chọn một mô hình nhanh, tiết kiệm hơn
- ANTHROPIC_DEFAULT_FABLE_MODEL=kimi-k3.1-pro
- CLAUDE_CODE_SUBAGENT_MODEL=kimi-k3.1-pro
- CLAUDE_CODE_AUTO_COMPACT_WINDOW=1000000
- CLAUDE_CODE_EFFORT_LEVEL=max
Thay mô hình mẫu ở tier HAIKU bằng mã một mô hình nhanh, phù hợp với tài khoản của bạn. Lỗi cấu hình Kimi thường gặp là đặt khóa vào ANTHROPIC_API_KEY thay vì ANTHROPIC_AUTH_TOKEN; Claude Code dùng biến thứ hai làm bearer token, nên cấu hình nhìn có vẻ hợp lệ vẫn có thể trả về 401.
Khai báo Kimi trong Codex bằng TOML
Codex đọc cấu hình ở ~/.codex/config.toml; trên Windows, đường dẫn là %USERPROFILE%\.codex\config.toml. Khác với Claude Code, Codex cần một khối nhà cung cấp trong TOML để chỉ rõ URL, tên biến chứa khóa và giao thức Responses.
Thêm cấu hình sau vào tệp:
[model_providers.kimi] name = "kimi" base_url = "https://api.moonshot.ai/v1" env_key = "MOONSHOT_API_KEY" wire_api = "responses" [models.kimi-k3.1-pro] name = "Kimi K3.1 Pro" model_provider = "kimi" model_context_window = 1048576
Đặt khóa trong biến môi trường MOONSHOT_API_KEY, rồi chọn kimi-k3.1-pro làm mô hình trong Codex. Đừng bỏ wire_api = "responses": đây là khai báo giao thức để Codex gửi yêu cầu đúng kiểu. model_context_window = 1048576 giúp công cụ nhận cửa sổ ngữ cảnh một triệu token thay vì dùng giá trị mặc định nhỏ hơn.
Kiểm tra và tìm lỗi âm thầm
Trong Claude Code, chỉ đặt ANTHROPIC_MODEL là chưa đủ. Công cụ dùng các tier riêng cho hội thoại, tóm tắt nền, tác nhân con và tác vụ tiện ích; tier bị bỏ trống có thể không báo lỗi rõ ràng mà khiến tác nhân chậm, lẫn lộn hoặc không xử lý được việc cần thiết. Hãy đặt các tier trong cùng một lần chỉnh sửa, khởi động lại Claude Code và thử một tác vụ xác nhận tác nhân con thực sự chạy.
Nếu tác nhân con bị treo, hãy kiểm tra tier của nó trước khi đổ lỗi cho mô hình. Cửa sổ nén tự động cũng cần khớp với ngữ cảnh: đặt quá thấp sẽ khiến Claude Code nén sớm, còn đặt quá cao có thể gây lỗi giới hạn ngữ cảnh.
Trong Codex, mở một phiên trên kho mã nhỏ và kiểm tra xem mô hình có báo cửa sổ 1M hay không. Nếu thấy giá trị mặc định nhỏ hơn, hãy kiểm tra lại model_context_window và khối TOML đã được đọc chưa. Khi cần tách lỗi cấu hình khỏi lỗi trong ứng dụng, có thể gửi yêu cầu một token tới tuyến Messages hoặc Chat Completions; phản hồi đúng sẽ là JSON.
Tóm lại, Kimi trong Claude Code cần đủ biến môi trường cho từng tier, còn Kimi trong Codex cần đúng khối TOML và wire_api = "responses". Thiết lập đáng công nếu bạn kiểm tra khóa, giao thức và từng đường gọi sau khi cấu hình; đừng chỉ dựa vào việc lời nhắc chính trả lời được.
