Chẩn đoán một agent

Hướng dẫn này chỉ cách tìm ra vì sao một agent không tạo ra lần chạy nào.

Hãy làm từ trên xuống: các lần chạy của chính agent trước, rồi đến backend của nó, rồi đến máy chủ, và cuối cùng là máy đang chạy.

1. Kiểm tra lịch sử chạy của agent

Cài đặt → Không gian làm việc → Agent → chọn agent → Nhật ký.

Mỗi lần chạy hiển thị nhãn trạng thái, thời lượng (“Running…” khi đang thực hiện), thời điểm bắt đầu và hoàn tất, PID và adapter đã dùng. Xem mở luồng sự kiện thô của lần chạy đó. Dừng buộc kết thúc một tiến trình đang chạy và đánh dấu lần chạy là “Killed by user”; Hủy đang chạy ở phần đầu trang làm điều tương tự với mọi lần chạy đang thực hiện của agent đó.

Hãy đọc như sau:

Không có lần chạy nào — việc điều phối đã không xảy ra. Lượt mention trong ô soạn thảo gồm @ cộng các ký tự từ (chữ cái, chữ số, dấu gạch dưới). Việc phân giải khớp chính xác hoặc khớp tiền tố với tên agent, nên @code-reviewer bị phân tích thành code và vẫn có thể đánh thức một agent tên code-reviewer. Tên có dấu cách không thể được mention như một token duy nhất. Sau đó chuyển sang bước 2.
Một lần chạy kết thúc ngay lập tức với lỗi — mở Xem. Lỗi không khởi chạy được backend hiện ra ở đây dưới dạng lỗi tiến trình.
Một lần chạy kẹt ở “Running…” — hãy dừng nó, rồi kiểm tra Hết hạn im lặng của agent trong tab Cài đặt. Nếu không đặt hết hạn, hệ thống dùng mặc định theo từng chế độ.
Một lần chạy đã hoàn tất nhưng không có đầu ra hữu ích — trạng thái trong nhật ký chạy vẫn là completed với một lần chạy kết thúc mà không có kết quả giao đã khai báo; tín hiệu đáng tin là phần văn bản tóm tắt, chứ không phải nhãn.

Tab Nhật ký không hiển thị chi phí. Muốn xem chi tiêu, hãy dùng bảng theo từng agent trong Quan sát → Phân tích.

2. Kiểm tra backend của agent

Cài đặt → Máy chủ → Nhà cung cấp mô hình (/settings/server/providers).

Danh sách Runner đã phát hiện hiển thị mọi adapter cùng kết quả thăm dò — một phiên bản đã cài, “Đang kiểm tra…”, hoặc “Không tìm thấy” — kèm đường dẫn đã phân giải và các chip khả năng đối với CLI tìm thấy. Nhấn Làm mới ở đầu trang để thăm dò lại.

Việc thăm dò chạy trên máy đang lưu trữ cc_server, chứ không phải trên máy bạn đang nhìn. Nếu bạn đang dùng máy khách web hoặc thiết bị đã ghép nối, “Không tìm thấy” nghĩa là CLI thiếu trên máy chạy máy chủ.

Hai điều cần xác nhận:

Agent có được đặt adapter hay chưa. Một agent có adapter trống sẽ được điều phối tới Control Center (tích hợp) và nhật ký chạy ghi lại cc-harness, nên bản ghi nêu rõ thứ đã chạy. Nếu cũng không có mô hình, nó hỏi Anthropic lấy mặc định — việc này thất bại với No credential for provider "anthropic" trừ khi bạn đã kết nối một tài khoản Anthropic. Các agent chuyên môn được tạo sẵn vốn không có adapter.
Adapter tích hợp có mô hình. Danh sách mô hình của nó lấy trực tiếp từ các nhà cung cấp được kết nối ở phần dưới của chính trang này, nên một nhà cung cấp không có thông tin xác thực đã lưu sẽ đóng góp 0 mô hình.

Bản thân danh mục adapter là cố định — không có cách nào đăng ký adapter mới. Điều bạn có thể thay đổi cho từng adapter ở đây là đối số khởi chạy và biến môi trường. Lưu ý rằng phần ghi đè biến môi trường theo từng adapter sẽ âm thầm lấn át tài khoản nhà cung cấp đã kết nối khi thông tin xác thực được phân giải.

3. Kiểm tra máy chủ

Cài đặt → Máy chủ → Kết nối & trạng thái (/settings/server/connection) cho biết máy khách này đang nói chuyện với máy chủ nào và máy chủ báo cáo những gì.

Với máy chủ không giao diện, GET /healthz cung cấp thông tin tương tự mà không cần máy khách. Theo thiết kế, endpoint này không yêu cầu xác thực và mở CORS:

curl http://localhost:9030/healthz

Nó trả về trạng thái của máy chủ, thời gian hoạt động tính bằng giây, số kết nối trực tiếp, cổng đã bind, phiên bản build và git SHA, phiên bản schema không gian làm việc, phiên bản danh mục RPC, id, tên và dấu vân tay danh tính của máy chủ, việc bind có không an toàn hay không, cùng khối codeGraph với các số đếm watching / indexing / pending. Khi một bộ nhớ đệm đã có lưu lượng, phản hồi cũng gồm khối caches; máy chủ demo thêm demo: true.

Hai điều đáng biết khi một thay đổi “chạy được trong kiểm thử nhưng không chạy trong ứng dụng”:

Ứng dụng desktop khởi chạy một binary cc_server dựng sẵn thay vì bản từ mã nguồn. Một thao tác RPC hay công cụ MCP mới sẽ không xuất hiện cho tới khi binary được xây lại, và nhật ký khởi động ghi cảnh báo khi git SHA của tiến trình con khác với của ứng dụng.
Ứng dụng desktop buộc kết thúc một máy chủ con nếu nó không in banner sẵn sàng trong vòng 20 giây và chuyển sang màn hình lỗi.

4. Kiểm tra máy đang chạy

Cài đặt → Máy chủ → Chẩn đoán & quyền riêng tư (/settings/server/diagnostics) là trang cấp máy đang chạy. Trang này gồm:

Sandbox — công tắc tổng, backend đã phát hiện và gợi ý cài đặt. Chỉ backend đã phát hiện là đến từ máy chủ; xem phần chú ý bên dưới. Không có điều khiển đặt lại.
Tìm kiếm ngữ nghĩa — vòng đời của mô hình embedding trên thiết bị: đã cài, đang tải xuống kèm tỷ lệ phần trăm, chưa cài, hoặc lỗi cài đặt. Cho tới khi nó được cài, bộ nhớ và tìm kiếm mã vẫn chỉ dùng từ khóa.
Hành vi hệ thống — giữ máy tính luôn thức trong khi agent chạy.
Mức nhật ký — hãy nâng mức này trước khi tái hiện một lỗi.
Quyền riêng tư — liệu nội dung diff thô có được chuyển tiếp tới mô hình của agent hay không và liệu báo cáo sự cố có được gửi đi hay không.

Việc phát hiện và việc thực thi giờ đã khớp với nhau: ở nơi bộ phát hiện báo có backend gốc, các lần chạy agent trên máy đó thực sự được bao bọc trong backend ấy. Nhưng bộ phát hiện là thứ duy nhất còn sống trong phần này. Công tắc tổng và bộ chọn backend là những tùy chọn được lưu trên thiết bị của bạn và máy chủ không đọc thứ nào trong số đó — công tắc riêng của máy chủ là --sandbox (on theo mặc định, off để từ chối).

Vì vậy một cảnh báo ở đây vẫn đáng để xử lý, nhưng thường thì đó không phải lý do khiến agent thất bại. Để xác nhận máy chủ đang ở trạng thái nào, hãy đọc nhật ký khởi động của nó: nhật ký in agent sandbox ON kèm ghi chú về backend, no OS-native agent sandbox on this host kèm gợi ý cài đặt, hoặc agent sandbox DISABLED by --sandbox off. GET /healthz không chứa trường sandbox nào.

Ở nơi không có backend — Windows luôn vậy, còn Linux hay WSL2 khi thiếu bwrap và socat — các lần chạy không được sandbox, và thứ giới hạn chúng là checkout của chính cuộc hội thoại, token forge chỉ đọc của nó và cổng push, các rào chắn hành động, việc làm sạch môi trường và bề mặt công cụ mà chế độ của nó cho phép.

Các lỗi thường gặp

Lần chạy không bao giờ bắt đầu và adapter hiện “Không tìm thấy”

Hãy cài CLI trên máy chạy máy chủ, rồi nhấn Làm mới trên trang Nhà cung cấp mô hình. Hoặc chuyển agent sang adapter tích hợp — vốn không cần CLI — và kết nối một nhà cung cấp trên cùng trang đó.

Agent không thể push hoặc mở pull request

Hãy đọc những gì git hoặc agent in ra. Control Center policy: … nghĩa là một quy tắc hành động đã từ chối hoặc một yêu cầu phê duyệt không được trả lời: hãy kiểm tra Push lên remote và Mở một pull request trong Cài đặt → Không gian làm việc → Quyền của agent. Nếu git báo Control Center không có thông tin xác thực GitHub nào push được, hãy cài GitHub App lên kho mã đó hoặc kết nối GitHub.

Tìm kiếm ngữ nghĩa không trả về gì hữu ích

Kiểm tra Cài đặt → Máy chủ → Chẩn đoán & quyền riêng tư → Tìm kiếm ngữ nghĩa. Cho tới khi mô hình embedding được cài, tìm kiếm chỉ dùng từ khóa. Các bản ghi được tạo trước khi mô hình được cài sẽ không bao giờ được bù dữ liệu, nên chúng vẫn chỉ dùng từ khóa kể cả sau đó.

Máy chủ hoàn toàn không khởi động

Cần có các thư viện native và không có chế độ suy giảm. Một dylib bị thiếu khiến cc_server từ chối khởi động và nêu tên thư viện đó trong lỗi. Hãy chuẩn bị các thư viện native bằng scripts/natives/build_natives.sh rồi xây lại binary máy chủ.

Một hành động bị từ chối âm thầm

Một quyết định rào chắn ở mức prompt mà không có người phê duyệt nào được kết nối sẽ bị từ chối, theo đúng thiết kế. Hãy kiểm tra các quy tắc của không gian làm việc trong Cài đặt → Không gian làm việc → Quyền của agent.