Vấn đề
Không gì làm gián đoạn quy trình làm việc bằng một lỗi SSH bất ngờ. Bạn cố gắng thêm khóa cá nhân (private key) vào agent để có thể push code hoặc đăng nhập vào máy chủ, nhưng thay vì thông báo thành công, bạn lại nhận được lỗi này:
error: communication with agent failed
Lỗi này thường xuất hiện trong PowerShell, Command Prompt hoặc terminal tích hợp trong VS Code. Điều đó có nghĩa là các khóa của bạn không được lưu tạm (cached). Kết quả là bạn phải nhập mật khẩu (passphrase) mỗi khi tương tác với kho lưu trữ Git từ xa.
Tại sao lỗi này xảy ra
Lệnh ssh-add thực chất chỉ là một người đưa tin. Nó cần giao tiếp với một tiến trình chạy ngầm có tên là OpenSSH Authentication Agent (ssh-agent). Dịch vụ này giữ các khóa đã giải mã trong RAM để bạn không phải nhập lại mật khẩu liên tục.
Trên Windows, agent này là một Dịch vụ Hệ thống (System Service). Mặc dù Windows mặc định có sẵn OpenSSH client, nhưng dịch vụ ssh-agent thường được đặt ở chế độ "Disabled" (Bị vô hiệu hóa) khi mới cài đặt. Khi bạn chạy lệnh, nó sẽ tìm kiếm kết nối "named pipe" tới dịch vụ. Nếu dịch vụ không chạy, kết nối sẽ bị ngắt và bạn nhận được lỗi.
Cách 1: Sử dụng PowerShell (Khuyên dùng)
Sử dụng PowerShell là cách trực tiếp nhất để khắc phục lỗi này. Bạn cần thay đổi kiểu khởi động của dịch vụ thành "Automatic" và kích hoạt tiến trình. Quá trình này chỉ mất khoảng 10 giây.
1. Mở PowerShell với quyền Administrator
Nhấn phím Win, nhập "PowerShell", chuột phải vào kết quả và chọn Run as Administrator. Bạn cần quyền quản trị cao nhất để sửa đổi các dịch vụ hệ thống.
2. Kiểm tra trạng thái dịch vụ
Kiểm tra xem dịch vụ có thực sự là nguyên nhân không bằng cách chạy lệnh:
Get-Service ssh-agent
Trong hầu hết các trường hợp, bạn sẽ thấy Status là "Stopped" và StartType là "Disabled".
3. Kích hoạt và Khởi chạy
Chạy hai lệnh sau để bắt đầu:
# Thiết lập dịch vụ tự động chạy mỗi khi Windows khởi động
Set-Service -Name ssh-agent -StartupType Automatic
# Khởi chạy dịch vụ ngay lập tức
Start-Service ssh-agent
Bây giờ, hãy thử thêm lại khóa của bạn. Nó sẽ hoạt động ngay lập tức:
ssh-add ~/.ssh/id_rsa
Cách 2: Sử dụng Windows Services Manager (Giao diện đồ họa)
Nếu bạn thích thao tác bằng chuột hơn là nhập lệnh, bạn có thể sử dụng công cụ quản lý chuẩn của Windows.
- Nhấn
Win + R, nhập services.msc và nhấn Enter. - Tìm OpenSSH Authentication Agent trong danh sách.
- Chuột phải vào đó và chọn Properties.
- Thiết lập Startup type thành Automatic.
- Nhấn Start. Thanh trạng thái sẽ chạy trong một hoặc hai giây.
- Nhấn Apply và đóng cửa sổ.
Lưu ý đặc biệt cho người dùng Git Bash
Git Bash (MinGW64) đôi khi bỏ qua dịch vụ hệ thống của Windows. Nếu bạn đã khởi chạy dịch vụ nhưng Git Bash vẫn báo lỗi, bạn có thể cần khởi chạy một instance agent cục bộ cho cửa sổ đó.
Chạy lệnh này bên trong Git Bash:
eval $(ssh-agent -s)
Lệnh này sẽ khởi tạo agent thủ công và thiết lập biến môi trường SSH_AUTH_SOCK cho phiên làm việc hiện tại của bạn.
Xác nhận khắc phục thành công
Để đảm bảo mọi thứ hoạt động trơn tru, hãy yêu cầu agent liệt kê các khóa hiện đang được tải:
ssh-add -l
Nếu agent đang hoạt động nhưng danh sách trống, nó sẽ thông báo: "The agent has no identities." Đó là một dấu hiệu tốt—nghĩa là kênh giao tiếp đã được mở. Nếu bạn thấy một chuỗi dài các chữ số và ký tự (fingerprint), khóa của bạn đã được tải thành công và sẵn sàng sử dụng.
Mẹo chuyên nghiệp cho SSH trên Windows
- Luôn để chế độ Automatic: Đừng đặt dịch vụ thành "Manual". Nếu làm vậy, nó sẽ không tự chạy sau khi khởi động lại máy, và bạn sẽ thấy mình quay lại đây đọc hướng dẫn này sau một tuần.
- Chú ý xung đột: Nếu bạn sử dụng PuTTY hoặc Pageant, đôi khi chúng có thể tranh chấp quyền quản lý khóa. Nếu vẫn gặp lỗi, hãy thử đóng Pageant để xem OpenSSH mặc định của Windows có hoạt động hay không.
- Quyền hạn tệp tin: Windows rất khắt khe về bảo mật. Nếu agent đang chạy nhưng không chấp nhận khóa của bạn, hãy chuột phải vào tệp
id_rsa, chọn Security > Advanced, và đảm bảo tài khoản người dùng của bạn là tài khoản duy nhất có quyền truy cập.