Runtime không tìm thấy Skill hoặc Agent

Dùng trang này khi cài Kit thành công nhưng runtime không liệt kê hoặc nhận diện Skill hay Agent mong đợi.

Khớp runtime session với bản cài

Xác nhận bốn thông tin từ output cài đặt ban đầu:

1. Tên Kit.
2. Runtime đích: claude-code, codex, cursor hoặc grok.
3. Scope: project hiện tại hoặc --global.
4. Các Skill đã chọn, gồm mọi filter --skills hoặc --exclude-skills.

Project install được discover từ project đó. Global install được discover từ user profile của runtime. Mở session runtime mới sau khi cài để nó tải inventory hiện tại, rồi dùng bề mặt discovery mà runtime đó hỗ trợ.

Ví dụ, gọi Skill tên ak:cook bằng cú pháp riêng của từng runtime:

/ak:cook Check this project   # Claude Code
$ak:cook Check this project   # Codex

Agent dùng bề mặt khác. Claude Code dispatch subagent đã cài; Codex tải Agent được định nghĩa bằng TOML và cung cấp runtime tool agent_<slug> tương ứng. Không có cú pháp gọi / hoặc $ không có nghĩa là Agent bị thiếu.

Kiểm tra destination khớp delivery đã chọn:

Kiểm tra adapter, không chỉ sự tồn tại của tệp

ak doctor --adapter claude-code --json
ak doctor --adapter codex --json
ak doctor --adapter cursor --json

Chạy lệnh cho target đã cài. Tệp tồn tại không chứng minh registration hoặc cấu hình runtime hợp lệ. Kiểm tra các adapter check và data.healthy; doctor mặc định vẫn thoát 0 khi báo cáo không khỏe. Trên Codex, dùng doctor như tín hiệu về sức khỏe adapter, không phải bằng chứng duy nhất cho Skill inventory đã cài; hãy xác minh discovery ngay trong runtime.

Hãy đọc codex_install_provenance như phân loại toàn bộ home, không phải check inventory Kit. ${CODEX_HOME:-~/.codex} là root dùng chung do người dùng sở hữu, vì vậy dòng này khỏe khi root chứa nội dung người dùng và không yêu cầu marker AgentKit cho toàn bộ home. Marker cũ không phải bằng chứng ownership hiện tại, còn thiếu marker không phải lý do để init, thay thế hoặc xóa Codex home. Manifest cùng ownership record theo Kit mới quản lý nội dung AgentKit.

Với bản cài Claude Code, dùng audit chỉ đọc đúng mode như mô tả trong Lỗi cài Kit. Nếu audit thoát 1, hãy xử lý drift được báo trước khi debug runtime discovery.

Đọc các bề mặt hook Claude đang active

Các check Claude Code hook_registration và hook_log kiểm tra mọi install surface đang active mà chúng quy được trong context hiện tại: scope user hoặc project, cùng delivery native hoặc plugin. Trong JSON, chi tiết registration liệt kê kit, scope, mode, đường dẫn manifest hoặc settings và registration bị thiếu dưới details.surfaces; chi tiết hook log liệt kê từng log active dưới details.logs.

Hook log chưa tồn tại vẫn là trạng thái khỏe trên surface mới và không chứng minh Skill hoặc Agent bị thiếu. Warning registration nêu surface bị ảnh hưởng. Khi Doctor in một lệnh sửa duy nhất không mơ hồ, hãy dùng đúng target, scope và delivery mode đó; nếu không, sửa rõ từng surface được nêu thay vì refresh route khác.

Khôi phục activation plugin Claude

Chỉ có file plugin chưa đủ để activate plugin Claude Code. Nếu bản cài cảnh báo không tìm thấy CLI claude, hãy chạy theo thứ tự hai lệnh đầy đủ được in trong cảnh báo:

claude plugin marketplace add "<marketplace-source>" --scope <project-or-user>
claude plugin install <kit>@<marketplace> --scope <project-or-user>

Dùng đúng source, plugin reference và cùng scope trong output cài đặt. Lệnh đầu đăng ký marketplace; lệnh thứ hai ghi nhận bản cài plugin trong Claude Code. Sau đó đóng và mở lại Claude Code trong đúng project. Cũng phải mở session Claude Code mới sau khi chuyển giữa native delivery và plugin delivery; session đang chạy không tải lại mode đó.

Khôi phục tool Agent của Codex

Skill và Agent Codex có đường discovery riêng. Skill là file native dưới .agents/skills và không cần AgentKit MCP server. Agent là file TOML được AgentKit runtime đã đăng ký cung cấp thành tool agent_<slug>.

Kiểm tra codex_mcp_registration trong báo cáo doctor Codex. Nếu check này báo thiếu [mcp_servers.ak-agent-runtime], hãy đăng ký một lần:

ak doctor --adapter codex --json
ak codex-agent-runtime register
ak codex-agent-runtime serve --list-only

Registration cập nhật ${CODEX_HOME:-~/.codex}/config.toml theo cách idempotent và giữ các MCP server entry khác. Lệnh list-only chỉ đọc và phải liệt kê các Agent mong đợi trước khi tiếp tục. Với Agent được stage trong project, chạy check từ project root và dùng project làm staging root:

ak codex-agent-runtime serve --list-only --plugin-root .

Override này xác minh <project>/<kit>/.codex/agents/; nó không chuyển Agent sang user scope hoặc viết lại server đã đăng ký. Nếu chỉ check có override tìm thấy Agent, hãy xử lý scope mismatch thay vì sao chép file TOML. Sau khi đăng ký hoặc sửa scope, đóng và mở session Codex mới để tải lại cấu hình MCP.

Nếu Codex không tìm thấy ak:team

Sự vắng mặt này là có chủ ý. Adapter Codex loại Skill Engineer ak:team vì Codex không cung cấp đầy đủ lifecycle Agent Teams mà workflow yêu cầu. Adapter không cài cách gọi $ak:team và không âm thầm thay bằng ordinary Codex subagent.

Install summary báo Capabilities excluded (unsupported on this target) và nêu ak-team; JSON dùng capabilityExclusions cùng capabilityExclusionSummaries. Refresh chỉ xóa bản ak-team cũ do AgentKit sở hữu khi ownership hash đã ghi vẫn khớp. Bản đã sửa, không có ownership hoặc là link được giữ lại, nhưng việc còn trên disk không làm chúng được hỗ trợ. Hãy chọn workflow Codex khác hoặc dùng ak:team trong runtime có chiếu Skill này và có live team lifecycle.

Nếu bản cài báo Hooks bị bỏ

Trên target Codex, bản cài thành công có thể chứa đúng dòng tóm tắt này:

[!] Hooks dropped (unsupported on this target): 1 group - see warnings

Đây là chẩn đoán partial projection được hỗ trợ, không phải lỗi cài đặt bị che. Nó có nghĩa là hook group được nêu dùng matcher cho các Claude tool không có tương đương trong namespace tool của Codex, nên group đó và các handler được nêu không được project. Các hook tương thích khác cùng Skill hoặc Agent đã cài là kết quả riêng; hãy kiểm tra các dòng tương ứng trong cùng install summary.

Con số này đếm matcher group, không phải tệp hoặc script. Output cài đặt JSON báo cùng giới hạn trong hooksDropped và droppedHookSummaries. Warning theo sau nêu event, matcher và handler bị ảnh hưởng.

Với Engineer, group PostToolUse có matcher Agent|Task|TodoWrite|TodoRead gọi session-state.cjs không được project, vì vậy group này không refresh task-state giữa session. Các group tương thích Edit|Write và * vẫn còn, và task-state vẫn refresh tại các ranh giới turn và subagent Stop cùng SubagentStop được hỗ trợ. Không thử lại với --force, sao chép cấu hình hook Claude sang Codex hoặc xóa home của runtime để loại bỏ cảnh báo.

Hook Codex lỗi trên Windows

Hook .cjs đủ điều kiện bên trong Codex home đã resolve có thể chạy từ đường dẫn có khoảng trắng qua sibling shim .cmd do AgentKit quản lý. Đường dẫn có khoảng trắng bên ngoài Codex home, đường dẫn có metacharacter của cmd.exe, basename shim không phải ASCII hoặc argument được bake không an toàn hay không phải ASCII vẫn không được hỗ trợ và sẽ tạo warning. Đường dẫn không có khoảng trắng tiếp tục dùng lệnh trực tiếp.

Không di chuyển hook bên ngoài vào Codex home hoặc sửa tay shim được generate như một workaround. Hãy giữ warning cùng diagnostics đã che dữ liệu nhạy cảm.

Ở global scope, AgentKit chỉ merge registration do nó sở hữu vào ~/.codex/hooks.json dùng chung, giữ cấu trúc của user hoặc nguồn khác, và xóa cấu trúc rỗng do AgentKit sở hữu khi owner cuối cùng rời đi. Không sửa tay ownership sidecar hoặc xóa rộng tệp hooks dùng chung.

Kiểm tra scope cấu hình

Từ cùng thư mục project với runtime session, chạy:

ak config prefs resolve
ak config prefs validate

Tệp project ghi đè preference người dùng. Preference tắt hook có thể thay đổi hành vi hook, nhưng không cài Skill hoặc Agent đang thiếu. Xem Lỗi cấu hình trước khi sửa tệp.

Sau khi đổi nơi lưu hook state hoặc cài lại hook registration, hãy restart session của runtime bị ảnh hưởng trước khi kiểm tra. Session cũ có thể vẫn giữ hook inventory và state path trước đó.

Xác minh kết quả

Sự cố được giải quyết khi báo cáo doctor cho adapter khỏe, audit áp dụng được không có drift và session runtime mới trong đúng scope liệt kê hoặc nhận diện item mong đợi. Nếu các check đều đạt nhưng discovery vẫn thất bại, export gói đã che dữ liệu nhạy cảm:

ak diagnostics export --json > agentkit-diagnostics.json

Ghi lại Kit, target, scope, các Skill đã chọn và phiên bản runtime cùng báo cáo.

Trang liên quan

• Lỗi cài Kit
• Cài Kit
• Lỗi cấu hình