Name: OpenCode
Author: OpenCode

Để 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/

Desktop App

Nếu bạn dùng OpenCode Desktop App và gặp vấn đề, hãy thử các bước sau.

Kiểm tra nhanh

Khởi động lại app — đôi khi chỉ cần restart là hết
Kiểm tra kết nối mạng — desktop app cần internet để hoạt động
Cập nhật phiên bản mới nhất — vào Settings > About > Check for Updates

Vô hiệu hóa plugins

Nếu app crash hoặc hoạt động bất thường, plugins có thể là nguyên nhân.

Kiểm tra global config

Mở ~/.config/opencode/opencode.json và xem có plugins nào không:

{
  "plugin": ["some-plugin"]
}

Thử comment hoặc xóa hết plugins, restart app.

Kiểm tra thư mục plugins

Xem trong các thư mục:

~/.config/opencode/plugins/
.opencode/plugins/ (nếu có)

Di chuyển tạm thời ra chỗ khác để test:

mv ~/.config/opencode/plugins ~/.config/opencode/plugins.bak

Xóa cache

rm -rf ~/.cache/opencode

Khởi động lại app — cache sẽ được tạo lại tự động.

Fix lỗi kết nối server

Xóa default server URL

Nếu desktop app không kết nối được, thử xóa server URL đã lưu:

rm ~/.local/share/opencode/desktop.json

Xóa `server.port` / `server.hostname` khỏi config

Kiểm tra config của bạn có setting server không. Nếu có, thử xóa hoặc comment chúng.

Kiểm tra environment variables

Đảm bảo các biến môi trường như OPENCODE_SERVER_PASSWORD, OPENCODE_SERVER_USERNAME không gây xung đột.

Linux: Wayland / X11 issues

Nếu desktop app không hiển thị hoặc có vấn đề về window:

Thử chạy với GDK_BACKEND=x11:
```
GDK_BACKEND=x11 opencode-desktop
```
Đảm bảo Wayland và X11 đều được cài đặt

Windows: WebView2 runtime

Desktop app trên Windows yêu cầu WebView2 Runtime. Nếu app không mở được:

Tải và cài từ Microsoft WebView2
Khởi động lại app

Windows: Hiệu năng chậm

Đảm bảo đang dùng WSL2 chứ không phải WSL1
Kiểm tra RAM còn trống
Đóng bớt tabs trình duyệt và các app nặng khác

Notifications không hiển thị

macOS: Vào System Settings > Notifications > OpenCode, bật notifications
Windows: Vào Settings > System > Notifications, bật cho OpenCode
Linux: Cài libnotify:
```
apt install libnotify-bin
```

Reset toàn bộ desktop app (phương án cuối)

Nếu mọi cách đều không được, reset toàn bộ:

# Xóa cache provider packages
rm -rf ~/.cache/opencode

# Xóa dữ liệu session
rm -rf ~/.local/share/opencode

# Xóa config (sẽ mất settings)
rm -rf ~/.config/opencode

Sau đó cài lại OpenCode và cấu hình từ đầu.

Nhận hỗ trợ

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

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.
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

Kiểm tra logs để tìm thông báo lỗi
Thử chạy với --print-logs để xem output trực tiếp trong terminal
Đả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)

Thử xác thực lại bằng lệnh /connect trong TUI
Kiểm tra API keys của bạn còn hợp lệ không
Đả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

Kiểm tra bạn đã xác thực với provider chưa
Xác nhận tên model trong config đúng chính xác
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:

Đầu tiên, xác nhận provider được cấu hình đúng theo hướng dẫn providers
Nếu vấn đề vẫn còn, thử xóa cấu hình đã lưu:
```
rm -rf ~/.local/share/opencode
```
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:

Xóa cache provider packages:
```
rm -rf ~/.cache/opencode
```
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.