> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nagare.smtdfc.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Khắc phục sự cố

> Chẩn đoán và xử lý các lỗi thường gặp khi dùng Nagare.

## Chạy nagare doctor

Bước đầu tiên luôn là:

```bash theme={null}
nagare doctor
```

Kết quả liệt kê từng mục kiểm tra kèm chi tiết. Xem ý nghĩa các mục tại [Tham chiếu CLI](https://docs.nagare.smtdfc.net/reference/cli.md#nagare-doctor).

## Lỗi thường gặp

> [accordion] command not found: nagare
>
> Thư mục `$HOME/.local/bin` chưa có trong `PATH`. Xem [Thêm vào PATH](https://docs.nagare.smtdfc.net/installation.md#them-vao-path).

> [accordion] Gateway process: not running — no PID file found
>
> Gateway chưa chạy. Mở một terminal và chạy `nagare gateway start`, giữ terminal đó mở.

> [accordion] Gateway HTTP reachable: cannot reach ...
>
> Gateway không chạy hoặc đang dùng cổng khác. Kiểm tra biến `NAGARE_GATEWAY_PORT` và đảm bảo cổng `9832` không bị chương trình khác chiếm.

> [accordion] RSA keyring: error
>
> Nagare không truy cập được keyring của hệ điều hành. Trên Linux, cần có dịch vụ Secret Service (ví dụ GNOME Keyring hoặc KWallet) đang chạy và đã mở khóa.

> [accordion] Module: nagare\_vector — missing
>
> Module bộ nhớ chưa được cài. Chạy lại script cài đặt.

> [accordion] Giao diện web báo chưa đăng nhập hoặc token không hợp lệ
>
> Token đã hết hạn (60 giờ) hoặc khóa trong keyring đã đổi. Chạy `nagare web` để đăng nhập lại, hoặc tạo token mới bằng `nagare auth token` rồi dán vào trang đăng nhập.

> [accordion] Nagare không trả lời
>
> * Kiểm tra đã thêm nhà cung cấp mô hình và chọn **Default model** trong **Settings → General**.
> * Kiểm tra API key và Base URL. Dùng chức năng lấy danh sách mô hình để thử kết nối.
> * Xem log gateway tại `~/.nagare/logs/app.log`.

> [accordion] Công cụ bị từ chối: approval is required but no approval channel is available
>
> Công cụ cần phê duyệt nhưng không có kênh nào nhận yêu cầu. Hãy mở cuộc trò chuyện trong giao diện web hoặc dùng Telegram để có thể phê duyệt.

> [accordion] Plugin không chạy hoặc ở trạng thái failed
>
> * Xem log tại `~/.nagare/logs/plugins/<package_name>.log`.
> * Kiểm tra các biến môi trường plugin cần (ví dụ `NAGARE_TELEGRAM_TOKEN`) đã được đặt **trước khi** khởi động gateway.
> * Checksum tệp thực thi không khớp: cài lại gói plugin.

> [accordion] Cài plugin thất bại do chữ ký không hợp lệ
>
> Gói đã bị sửa đổi sau khi ký, hoặc được ký bằng khóa khác với khóa trong `~/.nagare/trusted`. Xem [Ký số plugin](https://docs.nagare.smtdfc.net/plugins/signing.md).

## Log

| Thành phần | Vị trí |
| - | - |
| Gateway | `~/.nagare/logs/app.log` và đầu ra terminal chạy `nagare gateway start` |
| Plugin | `~/.nagare/logs/plugins/<package_name>.log` |
| Module | `~/.nagare/logs/modules/` |

## Báo lỗi

Mở issue tại [github.com/smtdfc/nagare/issues](https://github.com/smtdfc/nagare/issues), kèm kết quả `nagare doctor` và đoạn log liên quan.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.