Hướng dẫn ccodex-sleep-state: trực quan hóa việc tiếp quản Codex, cấu hình proxy và khắc phục sự cố kết nối

Giới thiệu dự án

ccodex-sleep-state là một công cụ cục bộ viết bằng Go, nhằm cải thiện các vấn đề có thể xảy ra trong quá trình sử dụng Codex như chất lượng phản hồi thay đổi, giới hạn lưu lượng, lỗi kết nối và xung đột cấu hình. Công cụ tập trung quản lý kết nối, lối ra proxy, thu thập turn-state, tiếp quản cấu hình và chẩn đoán sự cố vào một dịch vụ cục bộ cùng bảng điều khiển web, giúp giảm nhu cầu chỉnh sửa tệp cấu hình thủ công.

Cần hiểu rõ trước: công cụ này không tăng hạn mức tài khoản và cũng không đảm bảo chất lượng mô hình chắc chắn khôi phục sau khi đổi lối ra. Công cụ xử lý kết nối, cấu hình và X-Codex-Turn-State trong phản hồi, giúp dễ kiểm tra hơn kết quả thu thập, trạng thái chèn, đường đi của yêu cầu và nguyên nhân lỗi.

Dự án hiện vẫn đang ở bản thử nghiệm công khai. Chức năng có thể khác nhau giữa các Release; cần căn cứ vào ghi chú phát hành của phiên bản đã tải xuống. Không được hiểu việc một số mô hình hoặc quy trình nén kiểm thử thành công là tất cả tình huống đã được nghiệm thu.

Chức năng chính

• Bảng điều khiển web cục bộ: xem Codex đã được tiếp quản hay chưa, yêu cầu có đi qua dịch vụ hay không, tình trạng phiên và số lượng yêu cầu.
• Thu thập và chèn turn-state: gửi yêu cầu ngắn từ các lối ra ứng viên, kiểm tra state trong phản hồi và sử dụng theo quy tắc trong các yêu cầu tiếp theo.
• Nhiều phương thức xác thực: xử lý riêng đăng nhập ChatGPT chính thức, API key chính thức của OpenAI, cũng như API key của dịch vụ trung chuyển Responses hoặc CCS.
• Cách ly mô hình: hỗ trợ gpt-6-astra, gpt-5.6-sol và gpt-5.6-terra; state được cách ly theo tài khoản, thông tin xác thực và mô hình, không dùng lẫn giữa các mô hình.
• Proxy và subscription: hỗ trợ HTTP, HTTPS, SOCKS5, YAML của Clash/Mihomo, URI từng dòng và subscription URI Base64.
• Bảo vệ cấu hình: sao lưu cấu hình Codex trước khi tiếp quản và thử khôi phục khi dừng dịch vụ; khi cấu hình hỏng có thể vào bảng điều khiển sửa chữa.
• Chẩn đoán: có thể tải xuống thông tin chẩn đoán đã khử thông tin nhạy cảm hoặc chạy lệnh doctor để thu thập thông tin xử lý sự cố.

Chuẩn bị trước khi cài đặt

Trước tiên, hãy xác nhận Codex vốn có thể sử dụng bình thường khi không đi qua công cụ này. Với tài khoản chính thức, cần hoàn tất đăng nhập trước; khi sử dụng dịch vụ trung chuyển, hãy cấu hình API key của bạn trước.

Nếu đồng thời sử dụng CCS hoặc CC Switch, trước tiên hãy chọn provider, upstream và cấu hình xác thực cần dùng trong lần này, sau đó thoát Codex và tạm dừng việc chuyển đổi cấu hình. ccodex-sleep-state không tiếp quản cơ sở dữ liệu tài khoản của CCS; công cụ chỉ đọc provider hiện được Codex chọn và tạm thời kết nối điểm vào với dịch vụ cục bộ.

Chọn đúng gói cài đặt

1. Mở trang Releases của dự án.
2. Máy tính Windows thông thường chọn windows-amd64.
3. Thiết bị Windows ARM chọn windows-arm64.
4. Mac dùng chip Apple chọn darwin-arm64.
5. Mac dùng chip Intel chọn darwin-amd64.
6. Sau khi tải xuống, hãy giải nén đầy đủ; không chạy trực tiếp một tệp riêng lẻ trong gói nén.

Khởi động và khởi tạo

Sử dụng tập lệnh khởi động

Người dùng Windows nhấp đúp vào start.cmd, người dùng macOS nhấp đúp vào start.command. Sau khi dịch vụ khởi động, trình duyệt thường sẽ tự động mở bảng điều khiển quản trị cục bộ và vào thẳng phiên hiện tại, không cần sao chép mã quản trị trước.

Chương trình sẽ tạo cấu hình dịch vụ còn thiếu, sao lưu và kết nối với Codex. Khi bảng điều khiển hiển thị đã tiếp quản, cần khởi động lại Codex và tạo phiên mới, sau đó gửi một tin nhắn ngắn để kiểm tra. Phiên cũ không được chuyển đổi nóng, vì vậy không nên chỉ tiếp tục kiểm tra trong phiên hiện tại.

Sử dụng dòng lệnh để khởi động

Nếu gói phát hành không có tập lệnh khởi động, có thể thực thi setup trong thư mục chương trình. Lệnh Windows:

.\ccodex-sleep-state.exe setup

Lệnh macOS:

./ccodex-sleep-state setup

setup sẽ tạo cấu hình còn thiếu, khởi động dịch vụ và mở bảng điều khiển; không đặt lại subscription và proxy đã lưu. Nếu phiên bản cũ không hỗ trợ lệnh này, hãy nâng cấp lên Release mới hơn trước.

Nếu trình duyệt không tự mở, hãy truy cập thủ công địa chỉ quản trị theo đầu ra của terminal. Địa chỉ mặc định là http://127.0.0.1:17841/admin/, sau đó dán mã quản trị của lần này hiển thị trong terminal.

Bản thân chương trình khởi động không gửi yêu cầu đến mô hình, nhưng sau khi kết nối Codex, việc thu thập state có thể tiêu hao hạn mức thực tế. Nên giữ cửa sổ terminal mở trong thời gian dịch vụ chạy.

Hoàn tất kết nối lần đầu

1. Vào khu vực “Bắt đầu sử dụng” trong bảng điều khiển và xác nhận trạng thái cấu hình hiển thị đã tiếp quản.
2. Nếu không phát hiện proxy, mở “Subscription và proxy”, nhập địa chỉ HTTP, HTTPS hoặc SOCKS5 cục bộ, hoặc nhập subscription từ xa và tệp subscription cục bộ.
3. Trong “Cài đặt kết nối”, xác nhận quy tắc mô hình và tài khoản.
4. Bật hoặc tắt chèn trong “Chèn turn-state” tùy nhu cầu.
5. Khởi động lại Codex và tạo một phiên hoàn toàn mới.
6. Gửi một tin nhắn ngắn, sau đó quay lại bảng điều khiển để kiểm tra số lượng yêu cầu, phiên và chẩn đoán thu thập.

Khi chạy lần đầu và chưa đặt rõ chính sách dự phòng, setup mặc định sử dụng “chuyển tiếp bình thường khi không thu thập được state”. Nếu trước đó đã chọn rõ chế độ nghiêm ngặt, lựa chọn đó sẽ được giữ lại.

“Kết nối Codex bằng một cú nhấp” trên trang chủ chủ yếu dùng để kiểm tra và sửa lỗi kết nối, không phải bắt buộc nhấp sau mỗi lần khởi động. Proxy, subscription, mô hình và công tắc chèn hiện có cũng sẽ được giữ lại.

Hiểu về turn-state, 292 và 332

Công cụ tập trung vào X-Codex-Turn-State trong phản hồi upstream. Công cụ sẽ gửi yêu cầu ngắn từ các lối ra ứng viên, kiểm tra cấu trúc đóng gói, thời gian và số khối mật mã của state, rồi lưu giá trị phù hợp với quy tắc kinh nghiệm hiện tại; các yêu cầu tiếp theo sẽ mang theo giá trị đó và sử dụng lối ra tương ứng.

• Quy tắc tài khoản cá nhân: cấu trúc kinh nghiệm được dự án chấp nhận là 10 khối, thường dài 292 ký tự; 11 khối hoặc 312 ký tự không được xem là giá trị hợp lệ.
• Quy tắc Team hoặc Business: cấu trúc kinh nghiệm được dự án chấp nhận là 12 khối, thường dài 332 ký tự; 13 khối hoặc 356 ký tự không được xem là giá trị hợp lệ.

Các độ dài này không phải chỉ số chất lượng do OpenAI chính thức công bố. Phù hợp về độ dài không chứng minh mô hình chắc chắn đang ở trạng thái “đầy đủ”, và không phù hợp cũng không thể tự chứng minh proxy hỏng hoặc chất lượng mô hình suy giảm.

Tính năng tự động nhận diện sẽ tham khảo gợi ý gói dịch vụ trong yêu cầu hiện tại, không chỉ dựa vào độ dài để phán đoán tài khoản là Team. Khi gợi ý không rõ ràng, bảng điều khiển sẽ nêu quy tắc đang sử dụng; cũng có thể chỉ định thủ công Cá nhân hoặc Team.

Chọn chế độ nghiêm ngặt hoặc dự phòng chuyển tiếp bình thường

Chế độ nghiêm ngặt

Chế độ nghiêm ngặt không sử dụng state không hợp lệ. Khi thu thập thất bại, yêu cầu sẽ trả về nguyên nhân rõ ràng. Nếu người dùng đã chọn rõ strict, các lần chạy setup sau đó sẽ không tự động ghi đè lựa chọn.

Dự phòng chuyển tiếp bình thường

Dự phòng chuyển tiếp bình thường sẽ dừng chèn khi không có state khả dụng, nhưng vẫn chuyển tiếp yêu cầu chính thức qua lối ra đã chọn. Yêu cầu chính thức được chuyển tiếp tối đa một lần; thông tin trạng thái sẽ nêu rõ lần này không chèn state, không giả mạo thành thu thập thành công.

Chế độ này không đồng nghĩa với việc gỡ bỏ giới hạn lưu lượng. Khi gặp 401, 403 hoặc 429, dịch vụ vẫn tuân thủ quy tắc dừng; yêu cầu tạo chính thức đã gửi lên upstream sẽ không tự động gửi lại sau khi đổi lối ra.

Cấu hình proxy và subscription

Nếu đã cài phần mềm proxy, có thể nhập địa chỉ HTTP, HTTPS hoặc SOCKS5 trên máy trong trang “Subscription và proxy”. Kết nối tự động lần đầu chỉ kiểm tra các cổng SOCKS5 phổ biến trên 127.0.0.1, không quét mạng LAN và không đọc cơ sở dữ liệu tài khoản của phần mềm proxy.

Dự án cũng hỗ trợ YAML của Clash/Mihomo, URI từng dòng và subscription URI Base64. Bộ điều hợp outbound tích hợp gồm AnyTLS, SS, SSR, VMess, VLESS, Trojan, Hysteria, Hysteria2 và TUIC, nhưng không nhập TUN, DNS hoặc quy tắc hệ thống trong subscription.

Có thể kiểm tra kết nối, cố định lối ra hoặc khôi phục lựa chọn tự động trên trang “Định tuyến”. Cần lưu ý, kiểm tra kết nối thành công chỉ có nghĩa đường dẫn mạng khả dụng, không có nghĩa đã thu thập được state hợp lệ.

Phối hợp với CCS và dịch vụ trung chuyển

Đối với đăng nhập ChatGPT chính thức, công cụ có thể thu thập và chèn state, đồng thời cho phép tắt tính năng chèn. Đối với API key chính thức của OpenAI, công cụ chuyển tiếp theo kênh API và không coi đó là đăng nhập subscription ChatGPT.

Đối với API key của dịch vụ trung chuyển Responses hoặc CCS, công cụ giữ nguyên upstream và phương thức xác thực bằng API key, không gửi thông tin đăng nhập chính thức đến dịch vụ trung chuyển và không chèn state chính thức.

Nếu CCS thực sự chuyển provider, upstream hoặc phương thức xác thực, dịch vụ sẽ dừng chuyển tiếp để tránh gửi thông tin xác thực đến sai đích. Nên chuyển đổi theo thứ tự sau:

1. Dừng ccodex-sleep-state.
2. Chuyển cấu hình trong CCS.
3. Khởi động lại ccodex-sleep-state.
4. Khởi động lại Codex và tạo phiên mới.

Nếu xảy ra xung đột cấu hình, không xóa tệp giao dịch và không tùy tiện chỉnh sửa TOML thủ công. Hãy vào “Kiểm tra và sửa cấu hình”, xem trước thay đổi, ưu tiên giữ cấu hình hiện tại của CCS, sau đó tiếp quản lại.

Dừng dịch vụ và khôi phục cấu hình

Khi dịch vụ đang chạy, nên giữ cửa sổ terminal mở. Khi cần thoát, nhấn Ctrl+C trong terminal, chờ hoàn tất khôi phục cấu hình rồi mới khởi động lại Codex.

Đóng trình duyệt, tắt chèn state và dừng dịch vụ là ba thao tác khác nhau: đóng trình duyệt không dừng dịch vụ nền; tắt chèn vẫn có thể tiếp tục chuyển tiếp yêu cầu; chỉ khi kết thúc tiến trình dịch vụ mới bắt đầu quy trình dừng và khôi phục cấu hình.

Xử lý các sự cố thường gặp

Bảng điều khiển hiển thị “Chưa tiếp quản”

Dịch vụ khởi động không có nghĩa Codex đã hoàn tất kết nối. Hãy xử lý theo gợi ý cấu hình trong bảng điều khiển và xác nhận không sử dụng chế độ chỉ đọc --no-config.

Codex có thể trả lời nhưng bảng điều khiển không có yêu cầu

Trước tiên hãy khởi động lại Codex và tạo phiên mới. Nếu vẫn không có bản ghi, kiểm tra xem Codex có đang sử dụng một cấu hình, profile, dự án hoặc ghi đè cấp tác vụ khác hay không, hoặc có đang chạy đồng thời một phiên bản khác hay không.

Xuất hiện codex_config_changed hoặc 409

Mở “Kiểm tra và sửa cấu hình”, xem trước khác biệt, ưu tiên giữ cấu hình hiện tại của CCS, sau đó tiếp quản lại.

Xuất hiện state_unavailable hoặc 503 cục bộ

Kiểm tra quy tắc tài khoản, chẩn đoán thu thập và thời gian chờ. Nếu cần khôi phục sử dụng trước, có thể chọn rõ dự phòng chuyển tiếp bình thường hoặc tạm thời tắt chèn.

Xuất hiện state_shape_changed

Điều này có nghĩa cấu trúc state không phù hợp với quy tắc hiện tại. Yêu cầu chính thức có thể đã tiêu hao hạn mức; dịch vụ sẽ không tự động gửi lại. Hãy kiểm tra quy tắc tài khoản, upstream và các thay đổi gần đây thay vì chỉ đơn giản sửa quy tắc độ dài.

Xuất hiện 415

Phiên bản mới hỗ trợ mã hóa yêu cầu gzip và zstd của ứng dụng khách chính thức. Hãy xác nhận không chạy phiên bản cũ, sau đó xem thông tin chẩn đoán đã khử thông tin nhạy cảm.

Xuất hiện 502, 503 hoặc hết thời gian chờ

Kiểm tra lối ra proxy và trạng thái dịch vụ upstream. Không thể giải quyết sự cố mạng bằng cách sửa độ dài state.

Xuất hiện 401, 403 hoặc 429

Lần lượt kiểm tra trạng thái đăng nhập, quyền truy cập hoặc chờ giới hạn lưu lượng được khôi phục. Dự án không liên tục đổi IP để vượt qua các điều kiện dừng này.

Tệp cấu hình bị hỏng

Nếu JSON dịch vụ bị hỏng, setup sẽ mở bảng điều khiển sửa chữa chỉ đọc. Sau khi xác nhận bản sao lưu, hãy xây dựng lại và khởi động lại. Nếu TOML của Codex bị hỏng, trước tiên hãy giữ lại bản sao lưu, sau đó sử dụng quy trình xây dựng lại rõ ràng hoặc để CCS tạo lại; không suy đoán API key từ tệp hỏng.

Sử dụng doctor để thu thập chẩn đoán

Trước khi cung cấp thông tin xử lý sự cố cho người bảo trì, thành viên nhóm hoặc AI Agent, người dùng Windows có thể chạy:

.\ccodex-sleep-state.exe doctor

Người dùng macOS chạy:

./ccodex-sleep-state doctor

Khi phản hồi, thường chỉ cần cung cấp hệ điều hành, phiên bản Codex, phiên bản công cụ, thông báo lỗi và thông tin chẩn đoán cần thiết đã được khử dữ liệu nhạy cảm. Không gửi auth.json, mật khẩu quản trị, liên kết đăng ký đầy đủ, thông tin đăng nhập tài khoản hoặc toàn bộ thư mục dữ liệu.

Mẹo sử dụng nâng cao

Xác nhận thư mục cấu hình thực tế

Nếu đã thiết lập CODEX_HOME, công cụ sẽ sử dụng vị trí đó. Công cụ cũng hỗ trợ CCODEX_STATE_HOME và --data-dir. Khi không chắc hiện đang sử dụng cấu hình nào, hãy chạy:

ccodex-sleep-state paths

Không nên chỉ dựa vào tên thư mục để đoán vị trí cấu hình hiện tại.

Hiểu chi phí thu thập và thời gian chờ

Việc thu thập state sẽ sử dụng hạn mức thực tế. Mặc định, mỗi lượt sẽ thử tối đa 6 lối ra tiềm năng, mỗi lần thăm dò tối đa 20 giây và hai lượt thu thập cách nhau ít nhất 180 giây. Các yêu cầu tạo thông thường sẽ không tự động phát lại, vì vậy không nên xem việc thu thập hoặc chuyển lối ra là thao tác thử lại không mất chi phí.

Cách ly theo mô hình và tài khoản

Không dùng chung state giữa Astra, Sol và Terra. Sau khi thay đổi mô hình mặc định, hãy khởi động lại Codex hoặc tạo phiên mới. Việc mô hình có thực sự gọi được hay không vẫn phụ thuộc vào quyền tài khoản và việc hệ thống thượng nguồn có cung cấp mô hình tương ứng hay không.

Đánh giá thận trọng khả năng nén

Nhật ký dự án cho thấy tính năng nén từ xa V2 mới của Sol thực tế và việc tiếp tục trả lời sau khi nén đã thành công; kiểu V1 cũ kết nối trực tiếp với hệ thống thượng nguồn trả về 404. Chế độ cầu nối trước khi gửi mới chỉ hoàn tất kiểm thử với máy khách mô phỏng cục bộ; khi nghiệm thu bổ sung trong thực tế từng xảy ra lỗi truyền qua lối ra, do đó không thể coi mọi phương thức nén đều đã hoạt động hoàn chỉnh.

Giới hạn quan trọng và ranh giới an toàn

• Các mô hình hiện được hỗ trợ chỉ gồm gpt-6-astra, gpt-5.6-sol và gpt-5.6-terra.
• Hiện sử dụng Responses HTTP và SSE, không hỗ trợ WebSocket và cũng không cung cấp tính năng chuyển đổi giao thức tùy ý.
• Công cụ không mở quyền sử dụng mô hình thay cho tài khoản và cũng không âm thầm thay thế mô hình.
• Công cụ không chuyển proxy hệ thống, không làm mới đăng nhập Codex và không sử dụng thẻ đặt lại.
• Dịch vụ trung chuyển có thể kết nối không có nghĩa là cách tiếp cận turn-state cũng hiệu quả với dịch vụ đó.
• Giá trị xác thực và state đầy đủ sẽ không được ghi vào nhật ký thông thường; dự án không có telemetry và không tải nhật ký lên cho tác giả.
• Cấu hình proxy cục bộ và bản sao lưu khôi phục vẫn có thể chứa thông tin nhạy cảm, cần tự bảo quản cẩn thận.

Thông tin dành cho nhà phát triển

Dự án được viết bằng Go, trang quản trị tĩnh được nhúng vào tệp nhị phân nên không cần khởi động riêng dịch vụ frontend. Cấu trúc mã chính gồm:

• cmd/ccodex-sleep-state: lệnh, điểm vào một lần bấm và chẩn đoán.
• internal/codexconfig: phân tích provider, tiếp quản cấu hình, kiểm tra ngữ nghĩa và sửa lỗi có thể khôi phục.
• internal/gateway: cách ly mô hình và tài khoản, thu thập, nén và chuyển tiếp dạng luồng.
• internal/turnstate: quy tắc đóng gói state, giá trị hiện tại và giá trị dự phòng.
• internal/proxyroute: phân tích đăng ký và kết nối đi.
• internal/service: một phiên bản duy nhất, bảng điều khiển web, chuyển đổi cấu hình nóng và chẩn đoán yêu cầu.

Dự án sử dụng giấy phép GPL-3.0, phần proxy tái sử dụng Mihomo. Dự án này không có quan hệ trực thuộc với OpenAI, Mihomo hoặc GPT-Load.

Tóm tắt

Giá trị cốt lõi của ccodex-sleep-state không nằm ở việc cam kết loại bỏ giới hạn lưu lượng hoặc khôi phục chất lượng mô hình, mà là làm cho việc kết nối Codex, lối ra proxy, turn-state, sao lưu cấu hình và chẩn đoán lỗi trở nên dễ quan sát, dễ kiểm tra và có thể khôi phục. Khi sử dụng lần đầu, nên xác minh Codex nguyên bản hoạt động trước, sau đó chạy setup, xác nhận việc tiếp quản qua bảng điều khiển, khởi động lại Codex và tạo phiên mới. Khi gặp vấn đề, hãy ưu tiên xem chẩn đoán trên bảng điều khiển và chạy doctor; không tự ý sửa cấu hình hoặc làm lộ thông tin đăng nhập nhạy cảm.