Một tham số duy nhất đã làm sập toàn bộ yêu cầu tới GPT-5: Bài học về sự phụ thuộc API

Bạn nâng cấp mô hình của mình lên GPT-5.2. Mọi yêu cầu đều trả về lỗi 400. Agent của bạn thử lại (retry), kích hoạt chuỗi dự phòng (fallback chain), và cuối cùng hết thời gian chờ (timeout). Nhật ký hệ thống hiển thị:

{
  "error": {
    "message": "Unsupported parameter: 'max_tokens' is not supported with this model. Use 'max_completion_tokens' instead.",
    "type": "invalid_request_error"
  }
}

Một tham số bị đổi tên. Tỷ lệ thất bại 100%. Vấn đề OpenClaw #62130 đã kể lại câu chuyện này.

Đã xảy ra chuyện gì

Gia đình mô hình GPT-5.x của OpenAI đã loại bỏ hỗ trợ cho tham số max_tokens. Tham số thay thế, max_completion_tokens, thực tế đã có sẵn kể từ dòng mô hình o1 — tức là đã có nhiều tháng trùng nhau mà cả hai tham số đều hoạt động trên các mô hình cũ. Tuy nhiên, GPT-5.x đã vạch một ranh giới rõ ràng: tên tham số cũ sẽ bị từ chối triệt để bằng lỗi 400.

OpenClaw, giống như nhiều khung framework (agent framework) khác, đã hardcode max_tokens sâu trong lớp cung cấp OpenAI của nó. Mọi thứ hoạt động hoàn hảo với GPT-4o, GPT-4.5 và các phiên bản trước đó. Nhưng ngay ngày mà cấu hình được trỏ tới gpt-5.2, mọi yêu cầu đều thất bại.

Tại sao vấn đề này nghiêm trọng hơn vẻ bề ngoài

Việc thiếu một tính năng thì khá phiền toái. Nhưng một tham số bị đổi tên gây ra lỗi cứng (hard failures) thì rất nguy hiểm vì ba lý do sau:

1. Lỗi trông giống như có thể thử lại (nhưng thực tế không)

Lỗi 400 có nghĩa là "yêu cầu sai". Nhiều chiến lược thử lại coi các lỗi 4xx là lỗi tạm thời — có thể yêu cầu bị sai định dạng do điều kiện chạy (race condition), hoặc một middleware làm hỏng nó. Agent sẽ thử lại cùng một yêu cầu sai đó, nhận lại cùng một lỗi 400, và tiêu tốn ngân sách thử lại (retry budget) mà không làm được việc gì hữu ích.

2. Chuỗi dự phòng có thể không giúp được gì

Nếu cấu hình dự phòng của bạn gửi cùng một tham số max_tokens đến một mô hình GPT-5 khác trên hồ sơ nhà cung cấp khác, bạn vẫn sẽ nhận được cùng một lỗi 400 từ mọi ứng cử viên. Chuỗi dự phòng kích hoạt đúng cách nhưng mọi ứng cử viên đều thất bại y hệt nhau. Từ bên ngoài, nó trông giống như "tất cả các mô hình đều chết" trong khi thực tế là tất cả các mô hình đều đang từ chối cùng một tham số sai.

3. Hôm qua nó vẫn hoạt động

Phần tàn khốc nhất là: đoạn mã này đã hoạt động hoàn hảo trong nhiều năm. Không có cảnh báo ngừng hỗ trợ (deprecation warning) trong phản hồi API. Không có sự suy giảm dần dần. Chỉ một lần nâng cấp mô hình, tất cả bị phá vỡ. Tác giả của framework hoàn toàn không có tín hiệu nào về điều này cho đến khi người dùng thử nghiệm.

Mô hình: Bí danh tham số trong các API đang phát triển

Đây không phải là vấn đề riêng của OpenAI. Đó là một mô hình lặp đi lặp lại trong các API phát triển nhanh:

Nhà cung cấp	Tham số cũ	Tham số mới	Mô hình gây lỗi
OpenAI	max_tokens	max_completion_tokens	GPT-5.x
Anthropic	max_tokens_to_sample	max_tokens	Claude 3
Google	maxOutputTokens	maxOutputTokens (lồng khác nhau)	Gemini 2.x

Mọi nhà cung cấp LLM lớn đều đã làm điều này ít nhất một lần. Bề mặt API phát triển nhanh hơn các framework bao bọc nó.

Bản sửa lỗi thì đơn giản; Bài học thì không

Bản sửa lỗi ngay lập tức mang tính máy móc: phát hiện dòng mô hình, gửi tên tham số đúng. Chỉ cần vài dòng code. Pull request, hợp nhất (merge), phát hành (release).

Nhưng vấn đề sâu hơn là sự ghép nối (coupling) giữa framework và nhà cung cấp. Khi framework agent của bạn hardcode các tên tham số cụ thể của nhà cung cấp, mọi sự tiến hóa của API đều trở thành một thay đổi phá vỡ tiềm năng. Các phương án thay thế:

1. Bảng ánh xạ tham số được lập chỉ mục theo dòng mô hình — rõ ràng nhưng dễ bảo trì.
2. Ủy quyền cho SDK nhà cung cấp — để SDK chính thức xử lý việc đặt tên tham số.
3. Thương lượng khả năng — truy vấn các tham số được hỗ trợ của mô hình trước khi gọi.

Phương án 1 là điều hầu hết các framework đang làm. Phương án 2 thêm một dependency. Phương án 3 chưa tồn tại nhưng có lẽ nên có.

Những người xây dựng Agent cần chú ý điều gì

Nếu bạn đang vận hành một framework agent trong môi trường sản xuất (production):

• Ghim (pin) phiên bản mô hình một cách rõ ràng. Đừng sử dụng bí danh như gpt-5 tự động giải quyết thành phiên bản mới nhất. Hãy dùng gpt-5.2-2026-04-01 để bạn kiểm soát khi nào việc chuyển đổi diễn ra.
• Kiểm tra nâng cấp mô hình trong môi trường staging. Nghe có vẻ hiển nhiên, nhưng assumption "chỉ là thay đổi mô hình, không phải thay đổi code" chính là giả định gây ra sự cố.
• Giám sát tỷ lệ lỗi 400 theo từng mô hình. Một đợt tăng đột biến trong lỗi 400 sau khi thay đổi mô hình gần như luôn là vấn đề tương thích tham số.
• Kiểm tra nhật ký thay đổi (changelogs) trước khi nâng cấp. OpenAI đã tài liệu hóa việc chuyển đổi sang max_completion_tokens từ nhiều tháng trước. Thông tin đã có sẵn; chỉ là nó không được thực thi cho đến GPT-5.

Bài học rộng hơn

Các framework agent nằm tại một ranh giới tin cậy giữa ứng dụng của bạn và các API mô hình đang phát triển nhanh chóng. Mọi giả định được hardcode — tên tham số, định dạng phản hồi, mã lỗi — đều là một điểm có thể bị phá vỡ trong tương lai.

Những framework tồn tại được là những framework coi API của nhà cung cấp là giao diện không ổn định và xây dựng các lớp trừu tượng có thể hấp thụ các thay đổi mà không làm hỏng mọi người dùng downstream. Còn những framework không làm vậy... ну, họ sẽ làm hỏng mọi cuộc gọi GPT-5 chỉ với một tham số.