Cấu hình model Pi Coding Agent: /login, models.json và provider tùy chỉnh

Cấu hình mô hình của Pi coding agent có ba lớp: provider tích hợp dùng /login để đăng nhập (gói đăng ký hoặc khóa API) hoặc đặt biến môi trường; endpoint không tích hợp trong Pi nhưng tương thích với API OpenAI/Anthropic/Google được ghi vào ~/.pi/agent/models.json; chỉ dịch vụ cần xác thực hoặc giao thức đặc biệt mới cần tiện ích mở rộng. Sau khi chọn, dùng /model để chuyển đổi.Bài viết này dựa trên tài liệu Pi sau lần sửa ngày 22 tháng 9 năm 2026 và mã nguồn v0.99.2 phát hành ngày 30 tháng 9 năm 2026, giải thích cách cấu hình từng lớp, thứ tự đọc khóa (đã thay đổi sau lần sửa), ba giá trị mặc định của mô hình tùy chỉnh có thể âm thầm gây lỗi và ví dụ đầy đủ để kết nối endpoint tương thích OpenAI.

Trước hết hãy xác nhận bạn đang dùng Pi nào. Trang này nói về tác nhân lập trình terminal do công ty Earendil phát hành tại pi.dev, thư viện là earendil-works/pi (trước đây là badlogic/pi-mono), cấp phép MIT. Đây không phải chatbot Pi của Inflection (pi.ai), đồng Pi Network, Raspberry Pi hay Oh My Pi của một tác giả khác.

Trước tiên chọn cách kết nối

Ngay phần đầu của tài liệu mô hình Pi đã có bảng đối chiếu này:

Pi có một danh mục mô hình tích hợp và có thể bổ sung dữ liệu danh mục mới hơn từ pi.dev; khi ngoại tuyến, nó sử dụng bộ nhớ đệm, còn để buộc cập nhật có thể chạy pi update --models. Chỉ cần cấu hình mô hình tùy chỉnh khi Pi không có provider hoặc endpoint bạn cần.

Chọn mô hình trong Pi

• /model: tìm kiếm và chọn mô hình. Chỉ liệt kê các mô hình thuộc provider đã có thông tin xác thực khả dụng.
• Nhấn Ctrl+S trên mô hình: lưu làm mô hình mặc định của phiên làm việc mới.
• /thinking: chọn mức độ suy nghĩ của mô hình hiện tại; Pi chỉ liệt kê các mức mà mô hình đó hỗ trợ. Cũng nhấn Ctrl+S để lưu làm mặc định khi khởi động.
• Ctrl+P: luân phiên giữa các mô hình khả dụng; /scoped-models kiểm soát danh sách luân phiên và lưu lại.

Phiên làm việc ghi lại các thay đổi về mô hình và mức độ suy nghĩ; khi khôi phục phiên, các thay đổi này được khôi phục theo, nhưng không thay đổi mặc định của phiên mới.

Thứ tự đọc khóa (đã thay đổi sau lần sửa)

Khi đồng thời cấu hình nhiều nguồn khóa, tài liệu Pi ghi thứ tự là: --api-key trong thời gian chạy → thông tin xác thực lưu trong auth.json → apiKey trong models.json → biến môi trường của provider (hoặc thông tin xác thực môi trường của nền tảng đám mây). Vì vậy, khóa cũ đã lưu bằng /login sẽ ghi đè khóa bạn vừa ghi vào tệp; đây là nguyên nhân phổ biến nhất của tình trạng “đã thay đổi cấu hình nhưng vẫn dùng tài khoản cũ”. /logout có thể xóa thông tin xác thực đã lưu. Lưu ý: trước lần sửa ngày 22 tháng 9, tài liệu ghi biến môi trường đứng trước models.json, nên các hướng dẫn cũ trên mạng có thể vẫn dùng thứ tự cũ.

Một hiểu lầm phổ biến khác: mô hình không xuất hiện trong /model phần lớn là vấn đề xác thực chứ không phải JSON viết sai. Tài liệu nói mô hình tùy chỉnh có thể được tải từ models.json, nhưng trước khi Pi phân giải được thông tin xác thực, mô hình sẽ luôn ở trạng thái “không khả dụng”.

models.json: ví dụ đầy đủ để kết nối endpoint tương thích OpenAI

Ví dụ của Pi là Ollama cục bộ — khóa giả chỉ làm cho mô hình trở nên khả dụng; bản thân Ollama không kiểm tra khóa đó:

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "models": [{ "id": "qwen2.5-coder:7b" }]
    }
  }
}

Để kết nối một endpoint yêu cầu xác thực, chẳng hạn Kunavo, hãy viết như sau:

{
  "providers": {
    "kunavo": {
      "baseUrl": "https://api.kunavo.com/v1",
      "api": "openai-completions",
      "apiKey": "$KUNAVO_API_KEY",
      "models": [
        {
          "id": "claude-sonnet-5",
          "name": "Claude Sonnet 5",
          "reasoning": true,
          "input": ["text", "image"],
          "contextWindow": 1000000,
          "maxTokens": 128000
        },
        {
          "id": "claude-haiku-4-5",
          "name": "Claude Haiku 4.5",
          "input": ["text", "image"],
          "contextWindow": 200000,
          "maxTokens": 64000
        }
      ]
    }
  }
}

• baseUrl và api là bắt buộc.Có thể viết chúng ở cấp provider hoặc cấp mô hình; theo mã nguồn v0.99.2, nếu thiếu một trong hai, Pi sẽ không tải mô hình đó.
• api không phải lựa chọn một trong bốn.Trước lần sửa ngày 22 tháng 9, tài liệu Pi liệt kê bốn giá trị cho provider tùy chỉnh: openai-completions, openai-responses, anthropic-messages, google-generative-ai. Sau lần sửa, tài liệu không còn liệt kê danh sách, chỉ ghi “endpoint tương thích với OpenAI, Anthropic hoặc Google” trong bảng đối chiếu ở trên và ví dụ cũng chỉ dùng openai-completions. Mã nguồn v0.99.2 định nghĩa api là chuỗi tùy ý và chuyển cho một trong mười triển khai tích hợp tương ứng xử lý — bốn giá trị nêu trên, cộng với openai-codex-responses, azure-openai-responses, google-vertex, mistral-conversations, bedrock-converse-stream, pi-messages. Chỉ bốn giá trị đầu từng được tài liệu hóa như cách dùng cho provider tùy chỉnh; sáu giá trị còn lại chưa được kiểm thử ở đây và trang này cũng không khẳng định chúng có thể kết nối endpoint bên thứ ba.
• baseUrl của openai-completions phải có /v1.Tài liệu không quy định điều này trong một câu duy nhất, nhưng tất cả ví dụ endpoint tương thích đều có đường dẫn phiên bản. Thiếu /v1 sẽ nhận 404, không phải lỗi xác thực.
• Đừng ghi cứng khóa.apiKey và giá trị header có thể viết $NAME hoặc ${NAME} để tham chiếu biến môi trường, viết trực tiếp một giá trị hoặc dùng !指令 để lấy giá trị; tài liệu nói lệnh trong models.json được chạy mỗi lần yêu cầu và không được lưu vào bộ nhớ đệm. Hãy giữ bí mật auth.json và mọi lệnh lấy khóa.
• Sửa xong không cần khởi động lại.Khi mở /model, tệp sẽ được đọc lại. Các mục có cùng ID trong models sẽ thêm hoặc thay thế mô hình của provider đó; nếu muốn sửa metadata của mô hình tích hợp mà không thay thế toàn bộ danh sách, hãy dùng modelOverrides.

Ba giá trị mặc định có thể âm thầm gây lỗi

Lần sửa tài liệu ngày 22 tháng 9 đã xóa bảng trường, nhưng các giá trị mặc định vẫn có trong mã nguồn (v0.99.2 của provider-composer.ts). Nếu không điền, mô hình tùy chỉnh sẽ áp dụng:

Ngoài ra, reasoning mặc định là false và input mặc định chỉ có văn bản. Ví dụ Kunavo ở trên đã điền context và giới hạn đầu ra theo bảng giá, không đặt cost, vì ghi cứng giá trong tệp sẽ nhanh chóng lỗi thời — nếu muốn chi phí hiển thị ở cuối, hãy tự điền giá mỗi triệu token theo bảng giá. Pi cũng hỗ trợ promptCache (khai báo thời gian tồn tại của bộ nhớ đệm nhà cung cấp theo giây, dùng để làm nóng bộ nhớ đệm); tài liệu khuyến nghị chọn đầu bảo thủ trong phạm vi công khai.

anthropic-messages: có thể kết nối, nhưng baseUrl chưa có kết luận

anthropic-messages là một trong bốn giá trị mà tài liệu trước lần sửa liệt kê cho provider tùy chỉnh; Kunavo cũng cung cấp giao diện Anthropic Messages, nên tuyến api: "anthropic-messages" này tồn tại. Tuy nhiên, tài liệu Pi chưa bao giờ nói rõ baseUrl của loại này có cần có /v1 hay không: trước lần sửa, một ví dụ ghi https://proxy.example.com/v1, ví dụ khác dùng https://proxy.example.com không có đường dẫn; sau lần sửa, cả hai ví dụ đều bị xóa và vẫn không có kết luận. Nếu đi theo tuyến này, trước tiên hãy thử một cách; nếu yêu cầu đầu tiên trả về 404 (không phải 401), hãy sửa dòng này. Trong compat cũng có một số công tắc được thiết kế riêng cho endpoint không chính thức (chẳng hạn supportsEagerToolInputStreaming, supportsStrictTools), nhưng tài liệu nhắc rằng cấu hình tương thích nên mô tả “khác biệt hành vi đã được xác minh”, không nên bật chỉ vì endpoint tuyên bố tương thích với OpenAI hoặc Anthropic. Ví dụ openai-completions ở trên tránh được các vấn đề này; đó mới là lý do thực sự nên bắt đầu từ ví dụ này, không phải vì nó nhanh hơn.

Minh bạch và thanh toán

Nói rõ trước: đây là tài liệu tham khảo về cấu hình được tổng hợp từ tài liệu và mã nguồn của Pi, Kunavo chưa thực sự chạy endpoint của mình bằng Pi — chưa chạy phiên làm việc, chế độ streaming hay vòng lặp công cụ, cũng chưa xác nhận cuối cùng yêu cầu được định tuyến đến model nào. Hãy giữ lại tuyến bạn hiện có thể sử dụng và giao cho Pi một nhiệm vụ đọc/ghi tệp thực tế để thử; Pi phụ thuộc vào lệnh gọi công cụ ở hầu hết mọi bước, nên lần chạy đầu tiên như vậy sẽ dễ phát hiện nhất các vấn đề không tương thích về streaming hoặc định dạng công cụ. Trang cấu hình đầy đủ bằng tiếng Anh có tại Pi integration guide; phần so sánh các tuyến tính phí khác nhau (bao gồm gateway Radius của chính Earendil) xem tại Pi coding agent pricing.

Kunavo là dịch vụ nạp tiền trả trước, tính phí theo token và không có phí hàng tháng. Mức nạp tối thiểu là $10; thanh toán qua Stripe, tại Đài Loan có thể dùng thẻ tín dụng (Visa, Mastercard, American Express, JCB, UnionPay), Apple Pay, Google Pay và Link; JKoPay và LINE Pay không có trong danh sách được hỗ trợ. Xem Hướng dẫn thanh toán, sau đó bạn có thể tạo tài khoản và tạo khóa.

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

Đã xác minh ngày 1 tháng 10 năm 2026: các trang pi.dev/docs/latest/models (Choose a Model) và providers; src/core/model-config.ts và provider-composer.ts trong tag v0.99.2 của earendil-works/pi; cùng thông tin phiên bản từ GitHub API. Cũng trong ngày đó, đã xác minh riêng trường api: các giá trị hiện được liệt kê trên trang models (chỉ có openai-completions trong ví dụ Ollama), kiểu của api trong model-config.ts của v0.99.2 (chuỗi tùy ý, dòng 191 và 233), cách provider-composer.ts phân phối model tùy chỉnh (dòng 579), và BUILTIN_APIS trong packages/ai/src/compat.ts (dòng 180, tổng cộng mười loại). Kunavo chưa thực sự chạy endpoint của mình bằng Pi.