Tài liệu gốc 02 5 phútTiếng Việt + English
running_the_code/00_troubleshooting.mdXem bản gốc Bản dịch tiếng Việt
Bản dịch đầy đủ theo đúng cấu trúc tài liệu; code, liên kết và định danh kỹ thuật được giữ nguyên.
Khắc phục sự cố
Mọi thất bại được biết đến ở một nơi. Bộ bảo vệ khởi động của Decode chỉ kiểm tra chỉ sự hiện diện và in một dòng, không bao giờ truy nguyên — vì vậy hãy bắt đầu bằng cách khớp với dòng bạn có.
Dưới đây là các vấn đề về thiết lập và chạy lần đầu. Hai khu vực giữ các bảng riêng bên cạnh tính năng tạo ra chúng: chế độ hộp cát trong 04_sandboxing.md và runtime bền bỉ trong 03_runtime.md.
cài đặt
| Bạn thấy gì | Ý nghĩa của nó | Sửa chữa |
|---|---|---|
uv: command not found | uv đã được cài đặt nhưng chưa có trên PATH của bạn | khởi động lại vỏ của bạn. |
decode: command not found | make install-cli đã chạy, nhưng thùng công cụ của uv không có trên PATH | uv tool update-shell, khởi động lại trình bao. Hoặc bỏ qua cài đặt CLI và sử dụng uv run decode từ repository. |
modal: command not found | cái modal CLI là một phần phụ thuộc của dự án, không phải toàn cầu | chạy nó như uv run modal … từ repository (make install đã cài đặt nó rồi). |
uv sync phàn nàn rằng lockfile đã lỗi thời | pyproject.toml và uv.lock trôi dạt | uv lock sau đó make install. make ci thực thi điều này với uv lock --check. |
Nhà cung cấp và chìa khóa
| Bạn thấy gì | Ý nghĩa của nó | Sửa chữa |
|---|---|---|
Decode: set GEMINI_API_KEY in your environment or .env to start | không có khóa, khóa trống hoặc phần giữ chỗ không được điền (changeme) — cả ba đều đọc là chưa đặt | đặt một chìa khóa thực sự vào .env. Xác nhận với grep -c '^GEMINI_API_KEY=.\+' .env. |
Decode: LLM_PROVIDER=openrouter needs OPENROUTER_API_KEY … | nhà cung cấp đã chuyển đổi, khóa của nó chưa được đặt | đặt OPENROUTER_API_KEY, hoặc thả LLM_PROVIDER để quay trở lại với Song Tử. |
Decode: LLM_PROVIDER=modal needs MODAL_ENDPOINT_URL … | nhà cung cấp được đặt thành modal trước khi điểm cuối tồn tại | tạo điểm cuối (01_install_and_usage.md bước 3a), sau đó dán URL và id mẫu của nó vào .env. |
Decode: LLM_PROVIDER=modal proxy tokens are both-or-neither … | một trong MODAL_PROXY_TOKEN_ID / _SECRET được thiết lập | đặt cả hai hoặc không đặt cho một --unauthenticated điểm cuối. |
401 từ điểm cuối Modal của bạn | token proxy bị thiếu, không khớp hoặc không được phép trên env đó | đúc lại với uv run modal workspace proxy-tokens create, sau đó uv run modal workspace proxy-tokens allow wk-... main. |
| Lượt Modal đầu tiên bị treo rất lâu, sau đó mới hoạt động | khởi động nguội — GPU được điều chỉnh về 0 và đang hoạt động | dự kiến vào Min 0. Đặt COMPACTION_CONTEXT_WINDOW_TOKENS bỏ qua việc thăm dò khởi động; giữ ấm (Min ≥ 1) loại bỏ nó hoàn toàn nhưng tính phí GPU nhàn rỗi. |
429 / lỗi hạn ngạch giữa lượt | giới hạn mỗi phút hoặc hàng ngày của bậc miễn phí Gemini | đợi chút, chuyển sang LLM_PROVIDER=openrouterhoặc chuyển sang Modal — không có giới hạn tốc độ đối với điểm cuối của riêng bạn. |
token tài khoản (MODAL_TOKEN_ID / MODAL_TOKEN_SECRET) không là cài đặt decode — .env không làm gì cho họ sử dụng uv run modal token set …, viết ~/.modal.toml.
Điều hành agent
| Bạn thấy gì | Ý nghĩa của nó | Sửa chữa |
|---|---|---|
| agent mô tả công cụ mà nó sẽ sử dụng thay vì sử dụng nó | mô hình được ghim không có chức năng gọi công cụ | quay trở lại mặc định được vận chuyển (Qwen/Qwen3.6-35B-A3B-FP8, gemini-3.5-flash, openrouter/free). Hỗ trợ công cụ không phải là tùy chọn cho vòng lặp. |
Decode: no known context window for model …; assuming … | mang tính thông tin — mô hình không có trong bảng tĩnh và đầu dò không trả lời | vô hại; đặt COMPACTION_CONTEXT_WINDOW_TOKENS vào cửa sổ mà mô hình của bạn thực sự có và phần thăm dò bị bỏ qua hoàn toàn. |
/ không thể hiện kỹ năng demo | decode đã được khởi chạy bên ngoài kho khóa học — tải kỹ năng từ thư mục launch | khởi chạy lại từ repo hoặc sao chép .decode/skills/ vào dự án của bạn. |
--resume không tìm thấy gì | các phiên được thực hiện trên mỗi thư mục, trong phần khởi chạy cwd | khởi chạy lại từ cùng một thư mục; bảng điểm đang ở .decode/sessions/. |
| Công cụ LSP không trả lại điều gì hữu ích | cái ty máy chủ bị thiếu hoặc chậm; LSP là nỗ lực cao nhất và xuống cấp một cách âm thầm theo thiết kế | đó là sự phụ thuộc của nhóm nhà phát triển - make install (không phải là trần trụi uv sync --no-dev) cài đặt nó. |
| Truy tìm không hiển thị gì trong Opik | việc truy tìm dựa trên sự hiện diện; không OPIK_API_KEY nghĩa là không hoạt động trong im lặng | đặt OPIK_API_KEYvà OPIK_WORKSPACE nếu của bạn không default. Tệp dấu vết bên dưới decode-<DECODE_ENV> trừ khi OPIK_PROJECT_NAME ghi đè lên nó. |
Vẫn bị mắc kẹt?
Nhật ký không bao giờ chạm vào terminal - chúng ở .decode/logs/decode.log trong thư mục bạn đã khởi chạy từ đó. Bật lên chi tiết với LOG_LEVEL=DEBUG trong .env, sao chép, sau đó đọc phần đuôi.
Nếu điều đó không giải thích được, mở một vấn đề với cái đuôi đó cộng với nhà cung cấp và mô hình của bạn.