Khi OpenCode không hoạt động được với Ollama, hãy kiểm tra endpoint của server và ID model chính xác trước khi đổi model. Nếu cả hai đều ổn, hãy thử một thao tác sửa file nhỏ để phân biệt lỗi gọi công cụ với lỗi kết nối. Một model trả lời được yêu cầu chat mới chỉ vượt qua bước đầu tiên trong quy trình của coding agent.
Bài viết này giả sử bạn đã cài đặt Ollama và OpenCode. Để cài đặt và thiết lập provider, hãy xem hướng dẫn thiết lập Ollama với OpenCode. Quy trình dưới đây giúp tách biệt lỗi mà không phải thay đi đổi lại cấu hình đang chạy.
Xác định request nào đang bị lỗi
Lỗi OpenCode có thể xảy ra trước khi inference, trong quá trình sinh output, hoặc khi công cụ thực thi. Hãy kiểm tra từng giai đoạn riêng biệt. Lỗi từ chối kết nối và lỗi model trả về đoạn văn bản trông giống JSON là hai vấn đề hoàn toàn khác nhau. Ghi lại endpoint, model đang chọn, và thông báo lỗi trước khi thay đổi cài đặt — như vậy bạn mới biết thay đổi đó có giúp ích hay không.
| Quan sát | Kiểm tra tiếp theo | Kết quả cho biết điều gì |
|---|---|---|
| Kết nối bị từ chối | Gửi request /api/version đến host và port đã cấu hình | Endpoint Ollama đó có truy cập được không |
| Không tìm thấy model | Đọc /v1/models và so sánh ID chính xác | Model được yêu cầu có tồn tại trên server đó không |
| Chat hoạt động nhưng file không thay đổi | Kiểm tra lệnh gọi công cụ và kết quả cấp quyền | OpenCode đã thử và hoàn thành hành động chưa |
| Sửa nhỏ được, tác vụ lớn bị lỗi | Kiểm tra context được phân bổ và log runtime | Tác vụ lớn hơn có gặp giới hạn đo được không |
| Local chạy được, cloud bị treo | Kiểm tra riêng từng đường dẫn | Lỗi có chỉ xảy ra trên đường dẫn cloud không |
Ghi lại phiên bản trước khi tái tạo lỗi:
opencode --version
ollama --version
Các kiểm tra local trong bài viết này dùng OpenCode 1.19.4 và Ollama 0.32.9 trên Apple M3 Ultra với 96 GB bộ nhớ thống nhất. Phần cứng đó chạy được model 31B mà chúng tôi chọn; đây không phải khuyến nghị bộ nhớ cho laptop nhỏ hơn. Để chọn model phù hợp với phần cứng khác, hãy đọc hướng dẫn chọn model coding cho Ollama.
Kiểm tra endpoint trước khi đổi model
Gửi request đến đúng host và port mà OpenCode đang dùng. Server local tại 127.0.0.1:11434 và server tại 127.0.0.1:11435 là hai endpoint khác nhau. Nếu request thất bại, hãy sửa server hoặc địa chỉ trước — đổi model không thể sửa lỗi kết nối mạng bị từ chối.
curl --fail-with-body --max-time 5 \
http://127.0.0.1:11434/api/version
curl --fail-with-body --max-time 5 \
http://127.0.0.1:11434/v1/models
Phản hồi phiên bản xác nhận Ollama đã trả lời. Phản hồi danh sách model cho biết server đó đang cung cấp những ID model nào. Danh sách trống nghĩa là server truy cập được nhưng chưa có model nào được liệt kê — khác với lỗi kết nối.
Nếu Ollama đã dừng, hãy khởi động ứng dụng hoặc chạy server trong terminal:
ollama serve
Nếu port đã bị chiếm, hãy kiểm tra server nào đang chạy thay vì khởi động thêm một bản sao. Cài đặt Ollama từ xa cần địa chỉ từ xa tương ứng; 127.0.0.1 luôn trỏ đến máy đang chạy client.
Tài liệu tích hợp OpenCode của Ollama sử dụng base URL tương thích OpenAI, kết thúc bằng /v1. Giữ nguyên hậu tố đó trong cấu hình provider của OpenCode. Các route chẩn đoán gốc như /api/version nằm ngoài phạm vi này.
Khớp model đã cấu hình với ID chính xác trên server
Dùng ID model mà server trả về, bao gồm cả tag. Một model đã tải trên server Ollama này sẽ không khả dụng trên server khác trừ khi server đó cũng có cùng model. Kiểm tra provider đang chọn, base URL, và khai báo model cùng lúc trước khi thử lại request.
Đây là cấu trúc provider chúng tôi dùng cho các kiểm tra trên OpenCode 1.19.4:
{
"provider": {
"ollama": {
"npm": "@ai-sdk/openai-compatible",
"options": {
"baseURL": "http://127.0.0.1:11434/v1"
},
"models": {
"gemma4:31b": {
"name": "Gemma 4 31B",
"limit": {
"context": 65536,
"output": 2048
}
}
}
}
}
}
Thay gemma4:31b bằng ID mà server của bạn thực sự liệt kê. Ví dụ này không tải model đó xuống. Bộ chọn đầy đủ của OpenCode kết hợp tên provider và ID model:
opencode run -m ollama/gemma4:31b "Reply with one short sentence."
Chúng tôi đã cố tình request một model không tồn tại qua endpoint tương thích của Ollama và nhận HTTP 404 với not_found_error. Kết quả đó xác nhận đây là lỗi chọn model, không phải thiếu bộ nhớ hay tool parser bị lỗi.
Cấu hình cũng có thể đến từ nhiều nguồn. Tài liệu cấu hình của OpenCode mô tả cách các cài đặt được gộp lại. Khi một giá trị có vẻ bị bỏ qua, hãy kiểm tra cấu hình đã phân giải cục bộ:
opencode debug config
Cấu hình đã phân giải có thể chứa thông tin xác thực. Trích xuất phần cài đặt provider liên quan trước khi chia sẻ báo cáo chẩn đoán, và xóa các key hoặc thông tin tài khoản không liên quan.
Xác minh hành động bằng fixture code dùng một lần
Tự kiểm tra file đã thay đổi và tự chạy test. Đưa cho OpenCode một file nhỏ chứa một bug đã biết, yêu cầu nó sửa file, rồi chạy kiểm tra độc lập sau đó. Cách này kiểm tra quyền truy cập file, khả năng chỉnh sửa, và thực thi — đồng thời giữ phạm vi chẩn đoán đủ nhỏ để tự xem xét.
Tạo thư mục mới và di chuyển vào:
mkdir opencode-ollama-check
cd opencode-ollama-check
cat > add.mjs <<'JS'
export function add(a, b) {
return a - b;
}
JS
cat > check.mjs <<'JS'
import { add } from './add.mjs';
if (add(2, 3) !== 5) throw new Error('Expected add(2, 3) to return 5');
console.log('PASS');
JS
node check.mjs
Lần kiểm tra đầu tiên phải fail. Sao chép cấu hình provider đã test vào thư mục dùng một lần này, rồi chạy:
opencode run -m ollama/gemma4:31b \
"Read add.mjs. Fix add so it adds its arguments. Run node check.mjs."
node check.mjs
Tự kiểm tra add.mjs. Thông báo thành công từ model là chưa đủ nếu file vẫn thực hiện phép trừ hoặc bài kiểm tra độc lập fail. Giữ các prompt cấp quyền hiển thị để phân biệt được giữa thao tác sửa bị từ chối và lệnh gọi công cụ bị thiếu. Trong quá trình kiểm tra, macOS phân giải fixture dưới /private/tmp trong khi một tool lại yêu cầu alias /tmp. OpenCode coi đường dẫn alias là bên ngoài và từ chối trong lần chạy noninteractive. Dùng thư mục đã phân giải và đường dẫn file tương đối sẽ cho phép fixture chạy với quyền được giới hạn phạm vi hẹp.
Để kiểm tra sâu hơn, CLI của OpenCode hỗ trợ output JSON:
opencode run --format json -m ollama/gemma4:31b \
"Read add.mjs and explain the implementation."
Tìm công cụ đã thực thi và kết quả của nó. Văn bản chứa tên hàm hoặc đối tượng JSON không tự nó chứng minh OpenCode đã thực thi bất cứ điều gì. Sau khi sửa endpoint và quyền fixture, một lần chạy sửa đã đọc fixture, đổi phép trừ thành phép cộng, và pass bài kiểm tra Node độc lập. Lần chạy thứ hai cũng pass sau khi thay ID model cố tình không tồn tại. Trong cuộc thăm dò API trực tiếp riêng biệt, Gemma 4 31B trả về tool call read_file có cấu trúc ở context 65,536. Kết quả đơn lẻ đó xác thực định dạng phản hồi của cuộc thăm dò, chứ không chứng minh độ tin cậy trên mọi tác vụ coding.
Kiểm tra context mà Ollama thực sự phân bổ
Giới hạn model khai báo trong OpenCode và mức phân bổ runtime của Ollama cần khớp nhau. Tăng một con số trong cấu hình client không có nghĩa server đã phân bổ thêm context. Kiểm tra model đang chạy trong lúc có request, rồi so sánh context thực tế với prompt và lịch sử công cụ của tác vụ.
Tài liệu về context của Ollama khuyến nghị tối thiểu 64.000 token cho các công cụ lập trình và agent. Tài liệu cũng giải thích rằng phân bổ lớn hơn sẽ tốn nhiều bộ nhớ hơn. Server khởi chạy thủ công có thể đặt mức phân bổ cụ thể:
OLLAMA_CONTEXT_LENGTH=65536 ollama serve
Đặt biến đó trên tiến trình đang chạy Ollama. Chỉ export trong terminal chạy OpenCode sẽ không cấu hình lại ứng dụng Ollama đang chạy. Nếu ứng dụng quản lý server, hãy dùng cài đặt context của ứng dụng.
Trong khi model đang được nạp, hãy kiểm tra nó:
ollama ps
Xem cột CONTEXT và PROCESSOR. Nếu Ollama dùng host hoặc port tùy chỉnh, hãy trỏ CLI đến đúng server đó. Áp lực bộ nhớ, offload CPU, cắt ngắn context, và lỗi định dạng công cụ là những vấn đề riêng biệt — chỉ một phản hồi chậm không đủ để xác định nguyên nhân nào.
Nếu phần cứng không đáp ứng được context cần thiết, hãy chọn model nhỏ hơn có hỗ trợ công cụ và lặp lại cùng fixture. Tránh so sánh hai model bằng các tác vụ khác nhau rồi quy kết chênh lệch cho chất lượng model.
Viết báo cáo lỗi hữu ích
Một báo cáo hữu ích cho phép developer khác tái tạo được cùng request. Bao gồm: phiên bản, cấu hình provider đã che thông tin nhạy cảm, tag model chính xác, context được phân bổ, và fixture nhỏ nhất vẫn fail. Ghi lại xem request trực tiếp có thành công không và OpenCode có kết nối được đến server model không. Những chi tiết đó giúp maintainer xác định vị trí lỗi.
Hướng dẫn troubleshooting của OpenCode giải thích cách tìm log. Trên phiên bản đã test, lệnh này cho biết đường dẫn dữ liệu và log:
opencode debug paths
Giữ kết quả local và cloud riêng biệt. Bài test coding local không thể xác thực authentication hay tính khả dụng của Ollama Cloud, và sự cố cloud không chứng minh có hồi quy tool-use ở local. Tương tự, một issue cũ mô tả cùng triệu chứng không có nghĩa là bản sửa lỗi được đề xuất áp dụng cho phiên bản bạn đã cài.
Nếu fixture pass nhưng tác vụ trên repository fail, hãy giữ fixture đang chạy và tăng dần độ phức tạp: thêm file, đầu vào lớn hơn, hoặc chuỗi công cụ dài hơn. Thay đổi đầu tiên tái tạo được lỗi sẽ hữu ích hơn nhiều so với việc cài lại cả hai ứng dụng mà không có cơ sở so sánh.
Để cấu hình provider khác sau khi hoàn tất chẩn đoán local, hướng dẫn custom-provider của OpenCode có phần thiết lập Haimaker. Giữ các bài test local riêng tư ở local; chuyển provider là bước tiếp theo tùy chọn khi workload cho phép.
Câu hỏi thường gặp
Ollama chat thành công thì tool của OpenCode có hoạt động không?
Không. Phản hồi chat chỉ chứng minh model sinh được văn bản. OpenCode còn cần lệnh gọi công cụ có cấu trúc, quyền thực thi, và đủ context cho tác vụ. Hãy xác minh bằng một thao tác sửa file thực tế và kết quả test.
Tăng giới hạn context của OpenCode có làm Ollama phân bổ thêm bộ nhớ không?
Giới hạn context khai báo trong OpenCode không đồng nghĩa Ollama đã phân bổ context đó. Hãy cấu hình server Ollama và kiểm tra model đang chạy bằng ollama ps. Context lớn hơn cũng tốn nhiều bộ nhớ hơn.
Có nên cài lại tất cả khi model Ollama biến mất khỏi OpenCode không?
Trước tiên hãy so sánh ID model mà Ollama trả về với model khai báo trong cấu hình OpenCode. Kiểm tra endpoint và provider đang chọn trước khi cài lại bất kỳ ứng dụng nào.