Dùng Codex SDK hay App Server để thêm trợ lý rà mã vào công cụ nội bộ

Nhóm bạn muốn thêm nút “Rà thay đổi mã” vào công cụ nội bộ. Nhấn nút, hệ thống cần cho Codex đọc một kho mã, trả danh sách điểm cần kiểm tra, rồi để người duyệt quyết định. Nên dùng Codex SDK hay Codex App Server? Trong khoảng 30 phút, bài này giúp bạn chọn đường tích hợp và thử một đoạn Python chỉ đọc. Bạn cần quyền dùng Codex, một kho mã thử không chứa bí mật, Python từ 3.10 nếu chọn ví dụ dưới đây và người chịu trách nhiệm duyệt kết quả.

Theo tài liệu Codex SDK của OpenAI, SDK phù hợp khi bạn muốn chạy tác vụ lập trình trong chương trình, quy trình CI hoặc công cụ nội bộ. Codex App Server là giao diện giao thức cho ứng dụng cần tự quản lý đăng nhập, lịch sử hội thoại, yêu cầu phê duyệt và luồng sự kiện. Python SDK thực chất điều khiển app-server cục bộ qua JSON-RPC. Chọn SDK hay App Server là chọn mức tích hợp, không phải chọn hai bộ não AI khác nhau.

Chuẩn bị

Viết rõ yêu cầu: “Sau khi chọn repo, nút Rà thay đổi mã trả danh sách phát hiện để người duyệt kiểm tra.” Chốt ai được chọn repo, máy chạy ở đâu, dữ liệu được đọc và ai duyệt sửa đổi.

Nếu lập trình viên tự mở terminal để sửa một lỗi, hướng dẫn Codex CLI có thể đủ. Chỉ tích hợp khi nhóm cần quy trình lặp lại. Bài AI agent khác chatbot thế nào giải thích vì sao vẫn cần ranh giới và kiểm chứng.

Chuẩn bị một repo thử có lệnh test an toàn. Không dùng repo khách hàng ở lần đầu. Kiểm tra cách đăng nhập Codex trong môi trường chạy và chính sách sandbox. Đừng đưa khóa bí mật vào tệp mã hoặc vào prompt. Với việc có thể sửa tệp, xem thêm cách giới hạn quyền Codex cho nhóm.

Làm từng bước

1. Chọn SDK khi đầu ra là một kết quả cho job

Hãy hình dung công cụ nội bộ có nút “Kiểm tra repo”. Một job nhận thư mục dự án, nhờ Codex đọc và trả lời, ghi bản tóm tắt vào phiếu công việc. Người dùng không cần xem từng sự kiện nhỏ, đổi câu hỏi giữa chừng hay bấm duyệt lệnh ngay trong giao diện. Đây là tình huống bắt đầu bằng SDK.

SDK TypeScript chạy phía server với Node.js 18 trở lên, có thể bắt đầu, tiếp tục và khôi phục thread. SDK Python cần Python 3.10 trở lên; bản cài ổn định được phát hành bằng pip install openai-codex và kèm phụ thuộc Codex CLI đã ghim phiên bản. Bạn chỉ cần chọn ngôn ngữ phù hợp hệ thống, không cần cài cả hai. Với Python, tài liệu chính thức có các mức sandbox: read_only, workspace_write và full_access.

Lần rà đầu nên chỉ đọc. Trong repo thử, cài gói:

pip install openai-codex

Lưu đoạn sau thành review_repo.py. Mẫu dùng tên lớp và phương thức trong tài liệu SDK chính thức, bỏ chọn model cụ thể để dùng model mặc định mà tài khoản của bạn có quyền truy cập:

from openai_codex import Codex, Sandbox

with Codex() as codex:
    thread = codex.thread_start(sandbox=Sandbox.read_only)
    result = thread.run(
        "Read this repository and list three possible test gaps. "
        "Cite the relevant files. Do not edit anything."
    )
    print(result.final_response)

Chạy trong repo thử bằng python3 review_repo.py hoặc lệnh Python tương đương. Đầu ra để người đọc kiểm tra, không phải chứng nhận repo an toàn. Nếu đăng nhập hoặc sandbox lỗi, xử lý đúng quyền; đừng đổi sang full_access chỉ để chạy ví dụ.

Đây là ví dụ API tối thiểu đã đối chiếu với tài liệu OpenAI và kiểm tra cú pháp Python. Nó chưa được chạy gọi Codex thật trong dự án của bạn, nên không có bảo đảm về đầu ra hoặc quyền tài khoản. Khi thử thực tế, lưu lại phiên bản SDK, repo, thời gian, sandbox và lỗi để tái hiện.

2. Chọn App Server khi bạn xây một ứng dụng Codex đầy đủ

App Server phù hợp khi công cụ nội bộ cần hiển thị từng bước agent đang làm, giữ nhiều cuộc hội thoại, nhận yêu cầu phê duyệt, cho người dùng tiếp tục một thread và phản hồi sự kiện theo thời gian thực. Ví dụ trưởng nhóm mở trang nội bộ, xem Codex chạy test, bấm duyệt một thao tác, rồi tiếp tục hỏi về lỗi vừa thấy. SDK cơ bản có thể khởi chạy và lấy kết quả, còn ứng dụng kiểu này cần điều khiển vòng đời chi tiết hơn.

Theo tài liệu, App Server dùng các thông điệp JSON-RPC hai chiều. Với kết nối cục bộ, codex app-server mặc định dùng stdio và mỗi dòng là một thông điệp JSON. Luồng tối thiểu gồm:

1. Khởi động App Server và kết nối client.
2. Gửi initialize một lần cho kết nối, sau đó gửi thông báo initialized.
3. Gọi thread/start, nhận ID của cuộc hội thoại.
4. Gọi turn/start với ID đó và nội dung người dùng.
5. Đọc các thông báo tiến độ cho đến turn/completed, kể cả các yêu cầu cần xử lý theo quyền.

Đây là sơ đồ vòng đời, chưa phải mã client hoàn chỉnh. Client thật phải xử lý lỗi, ngắt kết nối, phê duyệt, xác thực và trạng thái phiên. App Server còn có thread/resume để tiếp tục lịch sử và turn/steer để bổ sung hướng dẫn vào lượt đang chạy. Đừng khởi động lại một thread mới mỗi lần người dùng gõ nếu sản phẩm cần giữ bối cảnh.

Với job đơn giản, tự viết client giao thức khiến bạn phải quản lý thông điệp, thread, phê duyệt và lỗi. Hãy chứng minh nhu cầu giao diện trước khi chọn App Server.

3. Đặt quyền và điểm dừng trước khi cho người khác dùng

Dù chọn cách nào, hãy tách đọc và đề xuất khỏi sửa và ghi. Bước đầu chỉ trả nhận xét có đường dẫn tệp. Người duyệt mở mã, chạy test, xác nhận từng phát hiện. Nếu muốn cho Codex sửa mã về sau, chuyển sang phạm vi ghi phù hợp, giới hạn repo, và yêu cầu duyệt bản khác biệt. Tài liệu SDK cho biết Sandbox.read_only chỉ đọc, workspace_write cho phép ghi trong workspace và các writable root được cấu hình, còn full_access không giới hạn truy cập hệ thống tệp.

Trong App Server, client phải xử lý phê duyệt và sự kiện. turn/completed không chứng minh mã đã được kiểm tra. Phân biệt job thất bại, có đề xuất và được người duyệt chấp thuận.

Nếu công cụ của bạn chỉ muốn gửi một câu hỏi AI tổng quát, không cần làm việc với repo và công cụ lập trình, hãy xem hướng dẫn Responses API bằng Python để chọn đúng API. Codex SDK dành cho tác vụ agent lập trình, không phải tên khác của Responses API.

4. Kiểm tra bản thử bằng ba tình huống

Thử trên ba repo: thiếu test dễ nhận ra, không có lỗi rõ và thiếu quyền đọc. Ghi yêu cầu, quyền, phản hồi, lỗi và kết luận người duyệt. Kiểm tra rằng thiếu quyền không tự mở rộng quyền, không thấy lỗi không bịa lỗi, có phát hiện thì chỉ được nơi kiểm tra lại.

Nếu dùng App Server, thử thêm client mất kết nối giữa lượt chạy, yêu cầu phê duyệt bị từ chối và việc tiếp tục một thread cũ. Với SDK, thử một job thất bại và việc ghi kết quả vào hệ thống nội bộ. Mục tiêu là biết người dùng nhìn thấy điều gì khi công việc không hoàn tất, chứ không chỉ có ảnh chụp màn hình của lần chạy đẹp nhất.

Kết quả mẫu

Một nhóm giả định muốn thêm nút “Rà khoảng trống test” trong trang quản lý repo. Vì giai đoạn đầu chỉ cần danh sách phát hiện, họ chọn Python SDK với Sandbox.read_only. Job chạy trên repo thử và trả ba chỗ cần người duyệt xem. Người duyệt kiểm tra mã: một phát hiện đúng, một phát hiện đã có test ở thư mục khác, một chỗ thiếu dữ liệu để kết luận. Hệ thống lưu cả ba trạng thái, không tự tạo pull request.

Sau vài tuần, nhóm muốn cho người dùng xem tiến độ, hỏi tiếp trong cùng cuộc trò chuyện và duyệt lệnh từ giao diện. Lúc đó họ lập bản thử App Server cục bộ để đánh giá vòng đời thread, turn và phê duyệt. Đây là tình huống minh họa, không phải cam kết rằng SDK hoặc App Server sẽ tự phát hiện đúng ba lỗi.

Mẹo để kết quả tốt hơn

Chọn theo giao diện người dùng. Nếu chỉ cần chạy job và nhận kết quả, SDK là điểm bắt đầu gọn. Nếu cần lịch sử, sự kiện và nút duyệt trong sản phẩm, nghiên cứu App Server.

Đừng nhầm thư viện với chính sách quyền. SDK là cách gọi Codex; sandbox và quyền vẫn phải được thiết kế. Không để prompt “đừng sửa” là ranh giới duy nhất khi có chế độ read_only.

Giữ bản thử nhỏ. Một repo giả, một nút, một người duyệt và ba trường hợp kiểm tra cho thấy vấn đề thiết kế sớm hơn việc xây ngay một bảng điều khiển lớn.

Giới hạn cần biết

Tài liệu chính thức hiện ghi kết nối WebSocket của App Server là thử nghiệm và chưa được hỗ trợ cho workload production. Dùng stdio cho bản thử cục bộ, và kiểm tra lại trạng thái hỗ trợ trước khi thiết kế kết nối từ xa. Không mở một WebSocket ra mạng công ty hoặc Internet theo ví dụ localhost mà chưa xử lý xác thực, TLS và quyền. Mẫu này không phải hướng dẫn triển khai production.

Đừng dựa vào ví dụ SDK để kết luận tài khoản nào cũng có quyền cùng một model; vì vậy mã trên dùng model mặc định. Phải đăng nhập, đáp ứng chính sách workspace và kiểm tra truy cập thực tế. Kết quả agent có thể sai hoặc thiếu. Một người chịu trách nhiệm vẫn cần đọc mã, kiểm tra test và duyệt thay đổi.

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

SDK và App Server có dùng hai Codex khác nhau không? Không. Đây là hai mức giao tiếp để điều khiển Codex. Tài liệu OpenAI nói Python SDK điều khiển app-server cục bộ qua JSON-RPC.

Có thể dùng SDK cho CI hoặc job chạy định kỳ không? Có. Tài liệu chính thức nêu CI/CD và job tự động là trường hợp dùng SDK. Bạn vẫn phải thiết kế đăng nhập, quyền, lỗi và bước duyệt theo môi trường của mình.

Khi nào cần App Server thay vì SDK? Khi sản phẩm của bạn cần client có lịch sử hội thoại, phê duyệt, thông báo tiến độ và điều khiển thread/turn. Nếu chỉ cần một kết quả cho job, bắt đầu bằng SDK.

Ví dụ Python trong bài đã chạy Codex thật chưa? Chưa. Đoạn mã được đối chiếu với tài liệu chính thức và kiểm tra cú pháp, nhưng lần chạy thật phụ thuộc gói đã cài, đăng nhập, repo và quyền của máy bạn.

Có nên dùng full_access để khỏi gặp lỗi quyền không? Không nên dùng làm mặc định. Ví dụ rà mã chỉ cần read_only. Nếu về sau cần sửa, hãy giới hạn phạm vi ghi, ghi nhận phê duyệt và kiểm tra diff trước khi áp dụng.

Nguồn chính: Codex SDK và Codex App Server, OpenAI Learn. Nội dung đối chiếu ngày 5/10/2026. #Codex #CodexSDK #AppServer #AIChoLapTrinh #VibeCoding