⚡
OpenCodeDocs

Để debug các vấn đề với OpenCode, bạn có thể kiểm tra logs hoặc dữ liệu session được lưu trữ cục bộ.

Logs

File logs được ghi tại:

  • macOS/Linux: ~/.local/share/opencode/log/
  • Windows: %USERPROFILE%\.local\share\opencode\log\

File logs được đặt tên theo timestamp (ví dụ: 2025-01-09T123456.log) và 10 file log gần nhất sẽ được giữ lại.

Bạn có thể đặt log level bằng option --log-level để xem thông tin debug chi tiết hơn. Ví dụ: opencode --log-level DEBUG.

Storage

OpenCode lưu trữ dữ liệu session và các dữ liệu ứng dụng khác tại:

  • macOS/Linux: ~/.local/share/opencode/
  • Windows: %USERPROFILE%\.local\share\opencode

Thư mục này chứa:

  • auth.json - Dữ liệu xác thực như API keys, OAuth tokens
  • log/ - Logs của ứng dụng
  • project/ - Dữ liệu theo project như session và messages
    • Nếu project nằm trong Git repo, dữ liệu được lưu tại ./<project-slug>/storage/
    • Nếu không phải Git repo, dữ liệu được lưu tại ./global/storage/

Nhận hỗ trợ

Nếu bạn gặp vấn đề với OpenCode:

  1. Báo lỗi trên GitHub

    Cách tốt nhất để báo bugs hoặc yêu cầu tính năng mới là thông qua GitHub repository:

    github.com/anomalyco/opencode/issues

    Trước khi tạo issue mới, hãy tìm kiếm các issues đã có để xem vấn đề của bạn đã được báo cáo chưa.

  2. Tham gia Discord

    Để nhận hỗ trợ realtime và thảo luận cùng cộng đồng, tham gia Discord server:

    opencode.ai/discord

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

Dưới đây là một số lỗi phổ biến và cách khắc phục.

OpenCode không khởi động được

  1. Kiểm tra logs để tìm thông báo lỗi
  2. Thử chạy với --print-logs để xem output trực tiếp trong terminal
  3. Đảm bảo bạn đang dùng phiên bản mới nhất với opencode upgrade

Lỗi xác thực (Authentication issues)

  1. Thử xác thực lại bằng lệnh /connect trong TUI
  2. Kiểm tra API keys của bạn còn hợp lệ không
  3. Đảm bảo mạng của bạn cho phép kết nối đến API của provider

Model không khả dụng

  1. Kiểm tra bạn đã xác thực với provider chưa
  2. Xác nhận tên model trong config đúng chính xác
  3. Một số models có thể yêu cầu quyền truy cập đặc biệt hoặc subscription

Nếu gặp lỗi ProviderModelNotFoundError, bạn có thể đang tham chiếu model không đúng cách. Models cần được tham chiếu theo format: <providerId>/<modelId>

Ví dụ:

  • openai/gpt-4.1
  • openrouter/google/gemini-2.5-flash
  • opencode/kimi-k2

Để xem danh sách models bạn có thể sử dụng, chạy lệnh opencode models

ProviderInitError

Nếu gặp lỗi ProviderInitError, có thể cấu hình của bạn bị lỗi hoặc hỏng.

Để khắc phục:

  1. Đầu tiên, xác nhận provider được cấu hình đúng theo hướng dẫn providers

  2. Nếu vấn đề vẫn còn, thử xóa cấu hình đã lưu:

    rm -rf ~/.local/share/opencode

  3. Xác thực lại với provider bằng lệnh /connect trong TUI.

AI_APICallError và lỗi provider packages

Nếu gặp lỗi API call, có thể do các provider packages đã cũ. OpenCode cài đặt động các provider packages (OpenAI, Anthropic, Google, v.v.) khi cần và cache chúng cục bộ.

Để khắc phục lỗi provider packages:

  1. Xóa cache provider packages:

    rm -rf ~/.cache/opencode

  2. Khởi động lại OpenCode để cài đặt lại các provider packages mới nhất

Thao tác này sẽ buộc OpenCode tải về phiên bản mới nhất của các provider packages, thường giải quyết được các vấn đề tương thích với model parameters và API changes.

Copy/paste không hoạt động trên Linux

Người dùng Linux cần cài đặt một trong các clipboard utilities sau để copy/paste hoạt động:

Cho hệ thống X11:

apt install -y xclip
# hoặc
apt install -y xsel

Cho hệ thống Wayland:

apt install -y wl-clipboard

Cho môi trường headless:

apt install -y xvfb
# và chạy:
Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &
export DISPLAY=:99.0

OpenCode sẽ tự phát hiện nếu bạn đang dùng Wayland và ưu tiên wl-clipboard, nếu không sẽ tìm clipboard tools theo thứ tự: xclip và xsel.