Chạy Kimi K3.1 Pro trong Claude Code và Codex: Cấu hình, những lỗi âm thầm và thao tác chuyển đổi chỉ một dòng

Kimi K3.1 Pro nói được ba giao thức: OpenAI Chat Completions, OpenAI Responses và Anthropic Messages. Đó chính là lý do nó có thể cắm thẳng vào Claude Code và Codex mà không cần proxy dịch — mỗi công cụ đã nói một trong ba giao thức, và Moonshot phục vụ giao thức đó một cách gốc. Việc thiết lập chỉ là một vài biến môi trường trong một trường hợp, và một khối TOML năm dòng trong trường hợp kia. Phần khiến người ta mất cả buổi chiều không phải là cấu hình; mà là kiểu lỗi. Claude Code dùng bốn hạng model khác nhau cho các công việc khác nhau, và bất kỳ hạng nào bị để trống sẽ lỗi âm thầm thay vì báo lỗi rõ ràng.

Hướng dẫn này được viết dựa trên tài liệu tích hợp của chính Moonshot, được kiểm tra vào ngày 24 tháng 10 năm 2026, kèm theo những lưu ý mà tài liệu thường ít nhắc tới. Ở những chỗ giá trị khác đi khi bạn trỏ cùng các công cụ đó vào một cổng định tuyến thay vì trỏ trực tiếp vào Moonshot, điều này sẽ được nêu rõ.

Tại sao không cần proxy

Claude Code talks to Anthropic's Messages API; Codex talks to the Responses API. Moonshot exposes both. Its Anthropic-compatible surface lives at https://api.moonshot.ai/anthropic and its Responses API at https://api.moonshot.ai/v1, and the model id is kimi-k3.1-pro on both. Nothing in either client needs to know it is not talking to the vendor it was built for.

Có một hệ quả đáng nêu trước phần cấu hình: mô hình luôn suy luận. Không có nút bật/tắt tư duy, và độ sâu được đặt bằng một trường cấp cao nhất reasoning_effort chấp nhận low, high và max, mặc định là max. Các tham số lấy mẫu là cố định — temperature 1.0, top-p 0.95, n bằng 1 — và truyền các giá trị khác sẽ trả về lỗi. Nếu thiết lập trước đây của bạn đã tinh chỉnh temperature, việc tinh chỉnh đó sẽ không được giữ lại khi chuyển đổi.

Claude Code: khối môi trường

Claude Code đọc cấu hình của nó từ envkhối ~/.claude/settings.json. Các biến được ghi ở đó sẽ ghi đè lên các biến cùng tên được export trong shell của bạn, đây vừa là một tính năng vừa là một cái bẫy: một export cũ trong terminal sẽ không cứu bạn nếu tệp lại ghi điều gì đó khác.

• ANTHROPIC_BASE_URL — the Kimi endpoint root. Set it to https://api.moonshot.ai/anthropic. If you leave it unset, requests go to Anthropic and fail authentication.

• ANTHROPIC_AUTH_TOKEN — khóa API Kimi của bạn. Đây là biến mà Claude Code thực sự dùng cho bearer token; việc đặt khóa API trong ANTHROPIC_API_KEY thay vào đó là lý do phổ biến nhất khiến một cấu hình trông có vẻ đúng lại trả về 401.

• ANTHROPIC_MODEL — mô hình hội thoại chính: kimi-k3.1-pro.

• ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_HAIKU_MODEL, ANTHROPIC_DEFAULT_FABLE_MODEL — mỗi tầng một biến. Tối thiểu hãy đặt ba biến đầu tiên, và trỏ HAIKU tới một mô hình rẻ, nhanh thay vì mô hình chủ lực; ví dụ của chính Moonshot ánh xạ tầng đó sang mô hình lập trình của họ.

• CLAUDE_CODE_SUBAGENT_MODEL — thứ mà các sub-agent sử dụng. Nếu không đặt, công việc của sub-agent sẽ bị giảm chất lượng hoặc thất bại.

• CLAUDE_CODE_AUTO_COMPACT_WINDOW — đặt thành 1000000, khớp với cửa sổ ngữ cảnh. Quá nhỏ sẽ nén sớm và vứt bỏ ngữ cảnh; quá lớn sẽ gây lỗi độ dài ngữ cảnh.

• CLAUDE_CODE_EFFORT_LEVEL — Hướng dẫn của Moonshot đặt giá trị này thành max, đây cũng là giá trị mặc định của mô hình. Việc hạ thấp nó làm giảm chất lượng trên các tác vụ phức tạp, và thay đổi nó giữa phiên sẽ làm mất hiệu lực các lượt trúng bộ nhớ đệm tiền tố.

Bốn tầng âm thầm thất bại

Đây là kiểu lỗi đáng để tính trước. Claude Code dùng các mô hình khác nhau cho cuộc hội thoại chính, tóm tắt nền, tác nhân con và các lệnh gọi tiện ích nhỏ. Chỉ cấu hình ANTHROPIC_MODEL và các đường dẫn khác sẽ không báo lỗi — chúng âm thầm không làm gì hữu ích, hoặc dự phòng theo những cách khiến công cụ có cảm giác bị hỏng mà không nêu nguyên nhân. Bảng tham chiếu của Moonshot nói rõ rằng mỗi tầng chưa được đặt sẽ khiến tác vụ tương ứng thất bại, và các triệu chứng trông giống một tác nhân chậm hoặc lẫn lộn hơn là một lỗi cấu hình.

Danh sách kiểm tra thực tế là đặt cả bốn biến tier cùng biến sub-agent trong một lần chỉnh sửa, khởi động lại Claude Code, rồi xác nhận trong một phiên rằng sub-agent thực sự chạy. Nếu nó bị đình trệ, tier là thứ đầu tiên cần kiểm tra, không phải model.

Codex: một khối TOML

Codex reads ~/.codex/config.toml (on Windows, %USERPROFILE%\.codex\config.toml). The connection is defined by four values in a provider block: the model id kimi-k3.1-pro, a provider named kimi, base_url pointing at https://api.moonshot.ai/v1, the environment-variable name that holds the key, and — the setting that makes the direct connection work — wire_api = "responses". Set model_context_window to 1048576 as well; without it Codex falls back to default model metadata, which degrades behaviour on long inputs.

Bản thân khóa nên nằm trong môi trường, không phải trong tệp. Codex đọc nó từ biến có tên trong env_key, vì vậy hãy giữ config.toml không chứa bí mật và đặt biến trong hồ sơ shell hoặc môi trường hệ thống của bạn.

Hai giới hạn cần biết trước khi bạn báo lỗi. Codex CLI không nhận video làm đầu vào dù bản thân mô hình thì có — đó là hạn chế của lớp đầu vào của Codex, nên công việc với video phải đi trực tiếp qua API. Và cơ chế quản lý ngữ cảnh của riêng Codex vẫn áp dụng: cửa sổ 1M token không có nghĩa là phiên nào cũng nên dùng tới mức đó.

Thay vào đó, trỏ cả hai công cụ vào cùng một gateway.

Mọi thứ ở trên vẫn hoạt động nguyên vẹn nếu bạn thay URL gốc của Moonshot bằng URL gốc của một gateway, điều này hữu ích khi cùng một codebase cũng gọi các mô hình từ những nhà cung cấp khác. OrcaRouter cung cấp cả ba giao diện cho Kimi K3.1 Pro — /v1/chat/completions, /v1/responses và /v1/messages — đồng thời công bố mô hình dưới id kimi/kimi-k3.1-pro.

For Claude Code, that means ANTHROPIC_BASE_URL set to the gateway root (https://api.orcarouter.ai) with the provider-prefixed model id in the four tier variables. For Codex, the same TOML block with the base URL pointing at https://api.orcarouter.ai/v1 and the model id kimi/kimi-k3.1-pro. The key variable stays the same shape; it just holds a gateway key instead of a vendor key.

Cái bạn nhận được khi thay thế là một thông tin xác thực duy nhất cho mọi mô hình trong danh mục và một chính sách định tuyến có thể chuyển yêu cầu giữa các nhà cung cấp mà không cần thay đổi mã ứng dụng — điều giúp kế hoạch dự phòng trở nên khả thi khi endpoint của một mô hình mới bị giới hạn tốc độ trong tuần ra mắt. Cái bạn phải đánh đổi là bảng điều khiển riêng của nhà cung cấp và mọi bề mặt beta dành riêng cho nhà cung cấp. Giá được chuyển thẳng theo giá niêm yết của nhà cung cấp: $2.00 cho mỗi triệu token đầu vào và $10.00 cho mỗi triệu token đầu ra đối với Kimi K3.1 Pro, không cộng thêm phụ phí.

Xác minh trong năm phút

• Gọi trực tiếp endpoint trước khi chạm vào client: một POST đến route Messages hoặc Chat Completions với yêu cầu một token sẽ trả về JSON, và lỗi 401 có nghĩa là khóa sai hoặc thuộc về nền tảng khác.

• Trong Claude Code, hãy đặt một câu hỏi buộc phải dùng sub-agent — tức là tìm kiếm trên nhiều tệp — và quan sát xem nó có hoàn thành không. Đó là bài kiểm tra nhanh nhất đối với cấu hình tier.

• Trong Codex, hãy bắt đầu một phiên trên một kho lưu trữ nhỏ và kiểm tra rằng mô hình báo cáo cửa sổ 1M; nếu nó báo cáo mặc định nhỏ hơn, model_context_window đã không có hiệu lực.

• Hãy đặt mức effort một cách có chủ đích, chỉ một lần, ngay từ đầu phiên: max cho việc gỡ lỗi khó, high cho các chỉnh sửa thông thường, low cho việc trích xuất và định dạng. Mặc định là max, và trên mô hình này đó là lựa chọn đắt đỏ.