Codex worktree: bản sao làm việc riêng cho nhiệm vụ thứ hai

Ví dụ, bạn đang dùng Codex CLI để tái cấu trúc một mô-đun thì phát sinh nhiệm vụ thứ hai: viết bài kiểm thử cho một mô-đun khác. Mở phiên thứ hai trong cùng một thư mục sẽ có rủi ro: bạn dễ nhầm lẫn các thay đổi của nhiệm vụ thứ nhất với nhiệm vụ thứ hai. Cờ --worktree tạo một thư mục riêng của cùng dự án cho nhiệm vụ thứ hai, giữ nguyên thư mục của nhiệm vụ thứ nhất.

Tài nguyên thực tế về cách làm việc với các tác nhân song song: tài liệu Ailoot.

--worktree tạo ra gì và những tệp nào được đưa vào bản sao#

Theo thuật ngữ Git, worktree là một thư mục làm việc bổ sung được liên kết với cùng một kho lưu trữ: nó dùng chung lịch sử commit nhưng có bộ tệp riêng trên đĩa. Trong Codex CLI 0.155.1, cờ --worktree sử dụng cơ chế Git này để khởi chạy một phiên tác nhân mới trong thư mục riêng, giữ nguyên thư mục nơi nhiệm vụ thứ nhất đang diễn ra.

Bản sao làm việc mới chứa các tệp từ commit mà HEAD của dự án gốc trỏ đến tại thời điểm khởi chạy—commit mới nhất, chứ không phải lần gần nhất bạn lưu tệp trong trình soạn thảo. Lệnh này không chuyển các thay đổi chưa commit hoặc tệp mới. Lưu trong trình soạn thảo không giống với commit trong Git. Nếu thư mục thứ nhất vẫn có các thay đổi chưa commit khi bạn khởi chạy nhiệm vụ thứ hai, các thay đổi đó sẽ chỉ nằm trong thư mục ấy.

Đây không phải là bản sao lưu toàn bộ kho lưu trữ hay cách ly toàn bộ máy tính. Đây là thư mục làm việc thứ hai của cùng dự án, có quyền truy cập vào cùng nhánh và lịch sử commit. Để xem cơ chế tương tự trong một công cụ khác, hãy xem Claude Code và git worktree: các nhiệm vụ song song.

Chuẩn bị: phiên bản, độ tin cậy của dự án và một commit#

Trước khi bắt đầu, hãy kiểm tra ba điều. Chạy các lệnh từ thư mục của dự án gốc.

Thứ nhất, kiểm tra phiên bản Codex CLI. Hướng dẫn này áp dụng cho phiên bản 0.155.1; với các phiên bản khác, hãy kiểm tra riêng cách hoạt động của các cờ:

codex --version

Thứ hai, bạn cần một dự án Git cục bộ có HEAD trỏ đến một commit hiện có—nói cách khác, kho lưu trữ phải có ít nhất một commit. Nếu không, sẽ không có gì để tạo bản sao từ đó.

Thứ ba, nguồn phải đáng tin cậy: nếu dự án được đánh dấu rõ ràng là không đáng tin cậy, việc khởi chạy với --worktree sẽ thất bại trước khi tạo bản sao. Nếu bạn mới thiết lập Codex CLI, phần chuẩn bị cơ bản được trình bày trong Codex (OpenAI): công cụ này là gì và cách bắt đầu.

Hãy kiểm tra trước danh sách các bản sao làm việc hiện có của kho lưu trữ này. Bạn có thể dùng danh sách đó để đối chiếu sau khi khởi chạy:

git worktree list

Các thư mục riêng giúp tách biệt nhiệm vụ. Để tìm hiểu cách tiếp cận tổng thể khi làm việc với một tác nhân, tài nguyên thực tế trong tài liệu Ailoot rất hữu ích.

Các bước: khởi chạy bản sao riêng cho nhiệm vụ thứ hai#

1. Bật tính năng thử nghiệm và khởi chạy phiên với bản sao riêng

   Chạy lệnh từ thư mục của dự án gốc, nơi bạn đang thực hiện nhiệm vụ thứ nhất.

   codex --enable worktrees --worktree
   

   Kết quả dự kiến: Codex tạo một bản sao làm việc mới của dự án từ HEAD hiện tại và mở phiên tác nhân trong đó. Bản sao ở trạng thái detached HEAD, không gắn với nhánh có tên nào. Đây là cách cờ này hoạt động trong phiên bản 0.155.1.

2. Liệt kê lại các bản sao làm việc trong một cửa sổ terminal khác ở dự án gốc

   git worktree list
   

   Kết quả dự kiến: đầu ra có thêm một dòng chứa đường dẫn của bản sao mới và dấu hiệu detached HEAD (hoặc một nhánh, nếu có). Danh sách này cho biết Git đã đăng ký bản sao, nhưng không xác nhận rằng tác nhân đã hoàn thành nhiệm vụ. Để chắc chắn các tệp đã có ở đó, hãy mở thư mục tại đường dẫn được liệt kê và kiểm tra nội dung.

Cách kiểm tra kết quả và bảo toàn công việc#

Sau khi hoàn thành nhiệm vụ thứ hai trong bản sao mới, bạn cần lưu và chuyển kết quả riêng. Lệnh --worktree không gộp các thay đổi vào nhánh chính và cũng không tự động chuyển kết quả. Bản sao vẫn ở trạng thái detached HEAD, vì vậy việc tạo commit bên trong bản sao không tự nó tạo ra một nhánh mới. Nếu cần bảo toàn các commit đó, hãy gắn chúng vào một nhánh hoặc chuyển chúng về dự án chính trước khi xóa thư mục của bản sao.

Đừng xóa thư mục của bản sao trước khi bảo toàn kết quả. Kiểm tra thư mục làm việc sạch không thay thế cho việc bảo toàn các commit bạn cần: chúng có thể vẫn chưa được gắn với nhánh nào.

Nếu bạn đồng thời làm việc với các nhiệm vụ trong những công cụ khác nhau, hãy lên kế hoạch trước cách ngăn chúng ảnh hưởng lẫn nhau. Cách làm việc cùng lúc với hai tác nhân được trình bày trong Claude Code và Codex cùng nhau.

Nếu quá trình khởi chạy bị gián đoạn: tìm bản sao ở đâu#

Khởi chạy với --worktree có thể thất bại vì một số lý do:

• tính năng chưa được bật trước đó và lệnh khởi chạy không có --enable worktrees: Codex sẽ từ chối khởi chạy với cờ --worktree;
• bạn đang ở sai thư mục hoặc không có commit: nếu thư mục hiện tại không phải là kho lưu trữ Git hoặc chưa có commit nào, sẽ không có gì để tạo bản sao từ đó;
• dự án được đánh dấu rõ ràng là nguồn không đáng tin cậy: Codex sẽ từ chối khởi chạy phiên với --worktree. Trước tiên, hãy chắc chắn rằng bạn đã mở đúng dự án. Đừng tự động thay đổi trạng thái tin cậy của dự án.

Nếu phiên không kết nối được với bản sao vừa tạo—ví dụ, do tiến trình bị gián đoạn—thư mục làm việc sẽ không tự động bị xóa. Trước tiên, hãy kiểm tra danh sách các bản sao làm việc, và trước khi xóa bất cứ thứ gì, hãy chắc chắn rằng không còn phiên Codex CLI nào đang dùng bản sao này:

git worktree list

Mở thư mục và lưu mọi thay đổi bạn cần trước khi xóa. Bản sao có thể vẫn còn dù phiên tác nhân chưa khởi chạy xong. Nếu bản sao tồn tại, không còn cần thiết và chắc chắn không được phiên nào sử dụng, hãy xóa thủ công bằng git worktree remove từ kho lưu trữ gốc, đồng thời chỉ định đường dẫn thư mục. Đừng thêm --force: nếu bản sao có tệp chưa commit hoặc tệp chưa được theo dõi, lệnh sẽ từ chối xóa. Nếu lệnh từ chối, hãy kiểm tra nội dung thư mục mà không vô hiệu hóa biện pháp bảo vệ.

Khi cập nhật Codex CLI, hãy kiểm tra lại codex --version và lặp lại bước kiểm tra bằng git worktree list: các cờ thử nghiệm có thể hoạt động khác nhau giữa các phiên bản.

Tài nguyên và công cụ khác: Ailoot.