Chuyển dự án từ Codex sang Hermes trên máy chủ

Để được trợ giúp khi sử dụng dịch vụ, hãy xem tài liệu Ailoot.

Cần chuẩn bị gì trước khi chuyển#

Repository là một thư mục dự án có lịch sử thay đổi trong Git. Bản sao làm việc chứa các tệp bạn chỉnh sửa. Nhiệm vụ ở đây là đưa bản sao đó lên máy chủ và tiếp tục phát triển. Bạn chưa cần đưa ứng dụng lên cho khách truy cập.

Nếu tác nhân chưa được cài đặt trên máy chủ, hãy bắt đầu bằng cài đặt Hermes Agent trên VPS. Trong trường hợp này, bạn cần một bản cài đặt Hermes hoạt động, terminal của máy chủ và Git. Bạn cần có một repository từ xa mà máy chủ truy cập được; nếu chưa có, hãy tạo trước rồi lưu dự án lên đó mà không có thông tin bí mật. Với repository riêng tư, hãy thiết lập trước quyền đọc từ tài khoản của bạn; đừng đưa token vào URL của repository hoặc tin nhắn gửi cho tác nhân.

Tạm dừng việc chỉnh sửa dự án song song trong lúc chuyển. Trên máy tính nguồn, mở terminal ngay trong thư mục dự án và chạy:

git status --short --branch
git status --short --ignored

Lệnh đầu tiên hiển thị nhánh và trạng thái các tệp. M nghĩa là đã chỉnh sửa, còn ?? nghĩa là tệp Git chưa theo dõi. Trong lệnh thứ hai, các tệp bị bỏ qua được đánh dấu bằng !!. Trạng thái sạch thông thường không chứng minh rằng bạn không có tệp cần thiết nào nằm ngoài Git.

Lưu các thay đổi cần thiết trong một commit riêng và đẩy nhánh phù hợp lên repository từ xa theo cách bạn thường dùng. Trước khi đẩy, hãy kiểm tra nội dung commit: không được chứa khóa, mật khẩu hoặc dữ liệu người dùng thật. Nếu chưa biết nên lưu những thay đổi nào, trước tiên hãy yêu cầu Codex liệt kê và giải thích mục đích của chúng, không xóa tệp hoặc đẩy lên repository.

Đừng cho rằng clone repository sẽ chuyển theo cơ sở dữ liệu bên ngoài, nội dung của thư mục bị bỏ qua hoặc các cuộc trò chuyện của bạn với Codex. Lịch sử trò chuyện, gói đăng ký, hồ sơ và thiết lập riêng của các tác nhân không thuộc phương thức chuyển này.

Sao chép đúng nhánh lên máy chủ#

Trước tiên, hãy lưu kết quả của lệnh này trên máy tính nguồn:

git status --porcelain=v2 --branch

Dòng # branch.oid hiển thị commit hiện tại, còn # branch.head hiển thị nhánh. Commit là phiên bản đã lưu của dự án. Với một dự án thông thường đã có commit, cách này cho phép bạn so sánh bản sao nguồn với bản sao mới; phép so sánh này không kiểm tra các thay đổi chưa được commit.

Trên máy chủ, chuyển đến thư mục nơi bạn sẽ lưu các dự án. Clone repository vào một thư mục mới. Trong mẫu bên dưới, thay REPOSITORY_URL bằng URL repository của bạn, BRANCH_NAME bằng tên nhánh bạn đã lưu và đẩy lên, và my-project bằng tên bạn muốn đặt cho thư mục mới:

git clone --branch BRANCH_NAME REPOSITORY_URL my-project
cd my-project
git status --porcelain=v2 --branch

Đây là mẫu, không phải URL có thể sao chép để dùng ngay. git clone tạo một thư mục và bản sao làm việc của nhánh đã chọn. Nếu thư mục đích đã tồn tại thì thư mục đó phải trống: đừng xóa nội dung để chạy lại lệnh; hãy chọn tên mới.

So sánh # branch.oid trong cả hai bản sao. Nếu các giá trị khác nhau, đừng bắt đầu sửa mã trên máy chủ: hãy kiểm tra nhánh đã chọn, các commit bạn đã đẩy lên và liệu có thay đổi song song nào không. Nếu kết quả trạng thái hiển thị các tệp đã chỉnh sửa, hãy kiểm tra riêng chúng. Đừng dùng thao tác dọn dẹp hoặc reset cưỡng bức để “làm cho chúng khớp nhau”.

Repository có Git submodule—các repository lồng bên trong—cũng cần tải nội dung của chúng. git clone có tùy chọn --recurse-submodules cho việc này; hãy dùng nếu dự án thực sự có submodule và URL của chúng đã được kiểm tra. Dự án có tài nguyên bên ngoài khác có thể cần thêm quy trình được mô tả trong README.

Khôi phục dependency theo quy tắc của dự án#

Trước tiên, hãy đọc README và các tệp cấu hình của dự án. Tìm hiểu phiên bản runtime cần dùng và package manager nào được sử dụng để cài dependency. Đừng thay công cụ thường dùng của dự án bằng npm chỉ vì npm xuất hiện trong ví dụ bên dưới.

Ví dụ giả định cho Node.js và npm: repository có các tệp package.json và package-lock.json nhất quán, đồng thời trên máy chủ đã cài phiên bản Node.js phù hợp với dự án. Trong trường hợp đó, hãy chạy lệnh này trong thư mục dự án:

npm ci

Theo tài liệu npm ci, lệnh này cài dependency cho toàn bộ dự án từ tệp khóa mà không viết lại package.json hoặc package-lock.json. Nếu nội dung của chúng không nhất quán, quá trình cài đặt sẽ thất bại. Mọi thư mục node_modules hiện có sẽ bị xóa trước khi cài đặt.

Nếu tệp khóa được tạo bằng các tùy chọn ảnh hưởng đến cây dependency, chẳng hạn như --legacy-peer-deps, thì npm ci cần dùng cùng các tùy chọn đó. Hãy kiểm tra hướng dẫn và thiết lập của dự án nguồn. Đừng xóa tệp khóa hoặc cập nhật toàn bộ dependency để che giấu lỗi đầu tiên khi chuyển.

Trước khi cài đặt, hãy kiểm tra các lệnh cài đặt và khởi động trong dự án của bạn. Chạy chúng trong một bản sao làm việc riêng không có quyền truy cập dữ liệu production, đồng thời đặt mọi giá trị môi trường cần thiết bên ngoài trò chuyện và Git. Nếu có thể, hãy dùng thông tin xác thực kiểm thử với quyền hạn chế để kiểm tra dự án. Nếu dự án phụ thuộc vào cơ sở dữ liệu hoặc tệp, trước tiên hãy khôi phục bộ dữ liệu kiểm thử được phép theo hướng dẫn; các tệp mã nguồn giống nhau không thay thế được dữ liệu đó.

Sau khi cài đặt, hãy chạy các bước kiểm tra có sẵn trong README: test và build nếu có. Tên lệnh tùy thuộc vào dự án. Cài dependency thành công chưa có nghĩa là ứng dụng đã hoạt động.

Mở bản sao làm việc trong Hermes#

Trong terminal của máy chủ, chuyển đến thư mục gốc của bản sao mới và khởi chạy tác nhân đã được cài đặt:

cd /absolute/path/to/my-project
hermes

Ở đây, /absolute/path/to/my-project là phần giữ chỗ cho đường dẫn đầy đủ đến dự án của bạn. Trên màn hình khởi động Hermes, hãy kiểm tra thư mục làm việc và môi trường nơi các lệnh terminal được chạy. Cách khởi động này dành cho môi trường terminal cục bộ của Hermes trên máy chủ. Nếu SSH hoặc Docker được cấu hình, tác nhân có thể chạy lệnh trong một môi trường khác; trước tiên hãy xác nhận rằng đường dẫn dự án có thể truy cập ở đó.

Yêu cầu tác nhân xác nhận thư mục làm việc thực tế bằng công cụ terminal của nó, sau đó đọc README và hướng dẫn của dự án. Đừng coi tên thư mục trong tin nhắn là xác minh đầy đủ.

Thứ tự bên dưới được nêu trong một phiên bản tài liệu đã được ghim và có thể khác với phiên bản Hermes đã cài đặt của bạn. Hãy kiểm tra hướng dẫn hiện tại trong phiên làm việc. Hermes hỗ trợ AGENTS.md, nhưng việc nó có đọc tệp này hay không phụ thuộc vào thứ tự ưu tiên của các tệp ngữ cảnh. Theo tài liệu Hermes chính thức, hệ thống chọn một loại tệp hướng dẫn theo thứ tự: .hermes.md, rồi AGENTS.override.md, AGENTS.md, CLAUDE.md và .cursorrules. Trước khi bắt đầu làm việc, hãy kiểm tra xem có .hermes.md cũ hoặc AGENTS.override.md cá nhân hay không: đừng cho rằng tác nhân chắc chắn sẽ áp dụng AGENTS.md cùng với tệp đó.

Trong các hướng dẫn được chọn, hãy giữ lại mục đích của dự án, các lệnh kiểm tra và những hạn chế về thay đổi. Đừng biến chúng thành kho lưu trữ hội thoại. Nếu cần chuyển cả thiết lập riêng của các tác nhân, đó là một quy trình khác; phạm vi được giải thích trong hướng dẫn chuyển từ Claude Code sang Codex.

Giao cho tác nhân một nhiệm vụ và kiểm tra kết quả#

Bắt đầu bằng cách đọc dự án mà không thay đổi gì. Ví dụ:

Chúng ta đang làm việc với một dự án hiện có trong thư mục tôi đã chỉ định.
Xác nhận thư mục làm việc thực tế bằng công cụ terminal.
Đọc README và hướng dẫn dự án hiện tại.
Đừng mở tệp chứa thông tin bí mật hoặc in các giá trị môi trường.
Liệt kê các lệnh kiểm tra và điều kiện tiên quyết để chạy chúng.
Hiện tại, đừng thay đổi hoặc cài đặt gì, và đừng đẩy lên repository.

Sau đó thống nhất một nhiệm vụ nhỏ, chẳng hạn sửa văn bản trong giao diện. Chỉ rõ tệp hoặc khu vực cần thay đổi và cấm cập nhật dependency ngoài dự kiến. Nếu muốn tách thử nghiệm khỏi bản sao chính, trước tiên hãy tìm hiểu về bản sao làm việc Git worktree riêng.

Đánh giá kết quả dựa trên các thay đổi của tệp và những lần kiểm tra lại dự án. Trước một thử nghiệm có thể thất bại, hãy lưu bản sao nguồn và một điểm khôi phục; đừng yêu cầu tác nhân reset hàng loạt mọi thay đổi. Nếu bước kiểm tra thất bại, hãy so sánh lỗi với bản sao nguồn: việc này giúp phân biệt sự cố khi chuyển với lỗi vốn đã có từ trước.

Có thể xem việc chuyển đã hoàn tất khi phiên bản tệp mã nguồn cần thiết đã sẵn sàng, môi trường đã được khôi phục, dữ liệu cần thiết có trong môi trường kiểm thử an toàn, các bước kiểm tra đều đạt và Hermes đang hoạt động chính xác trong thư mục này. Đưa ứng dụng lên cho khách truy cập là giai đoạn tiếp theo riêng biệt và không thuộc bước kiểm tra này.

Hãy tìm hiểu về Ailoot.