Dùng Ollama với coding agent: base URL và context

Điểm kết nối

Bạn có thể dùng Ollama với coding agent. Việc kết nối đơn giản hơn nhiều người nghĩ. Bạn chỉ cần đổi một base URL và chọn một tên model. Trường API key vẫn yêu cầu một giá trị, nhưng server local sẽ bỏ qua giá trị đó, nên chuỗi nào cũng được.

Ollama lắng nghe trên port 11434 và đồng thời cung cấp 3 API surface. /api là API native của Ollama. /v1 là lớp tương thích với OpenAI, bao gồm nhiều dạng: /v1/chat/completions, /v1/responses, /v1/completions, /v1/models và /v1/embeddings. Tài liệu Ollama mô tả key ở đó là bắt buộc nhưng bị bỏ qua. Surface thứ ba tương thích với Anthropic: client dùng http://localhost:11434 làm base URL và thêm /v1/messages vào cuối. Đây là định dạng mà Claude Code sử dụng. Hầu hết agent dùng /v1/chat/completions, Codex dùng /v1/responses, còn Claude Code dùng /v1/messages. Agent của bạn đã hỗ trợ một trong các giao diện này, nên không cần thay đổi phần nào khác.

Phần này chỉ mất 5 phút. Kết quả có dùng được hay không phụ thuộc vào 2 setting mà hầu như không ai thay đổi: context length và keep-alive. Kết quả cũng phụ thuộc vào việc giao cho model đúng loại công việc mà nó xử lý tốt. Mỗi setting sẽ có một section riêng. Phần cuối nêu rõ các giới hạn thực tế.

Những coding agent nào chấp nhận base URL cục bộ

Bài kiểm tra chỉ có một câu hỏi: công cụ có cung cấp tùy chọn cấu hình base URL không? Nếu có, công cụ đó có thể kết nối đến server của bạn.

Ollama có các trang hướng dẫn tích hợp cho Claude Code, OpenCode, Codex, Cline, Roo Code, Zed, JetBrains IDEs và VS Code. Aider cũng có tài liệu riêng về hỗ trợ Ollama. Danh sách này bao phủ hầu hết những công cụ thường được gọi là coding agent vào tháng 10 năm 2026. Các công cụ này không dùng cùng một API shape, và khác biệt đó là nguyên nhân khiến nhiều cấu hình bị lỗi.

• Hầu hết agent cần một endpoint tương thích với OpenAI. Cung cấp cho chúng base URL http://localhost:11434/v1 và bất kỳ chuỗi API key không rỗng nào.
• Claude Code hoàn toàn không chấp nhận OpenAI base URL. Công cụ này dùng Anthropic Messages API, nên cần đặt ANTHROPIC_BASE_URL thành http://localhost:11434, nơi Ollama cung cấp /v1/messages.
• Codex dùng OpenAI Responses API. Ollama cũng cung cấp /v1/responses, được bổ sung từ version 0.13.3.
• Agent không có tùy chọn base URL thì không thể chuyển hướng, vì endpoint được tích hợp sẵn trong client. Nếu agent chấp nhận URL tùy chỉnh nhưng cần một API shape khác, hãy đặt một translation layer phía trước, chẳng hạn như LiteLLM gateway tự host, rồi expose lại model theo đúng shape mà client yêu cầu.

Ollama có thể tự ghi các cấu hình này cho bạn. ollama launch opencode khởi chạy OpenCode với config inline cho model bạn chọn, ollama launch claude làm tương tự cho Claude Code, còn ollama launch droid --config ghi config mà không khởi chạy công cụ.

Cài đặt Ollama và pull một model có thể gọi tool

curl -fsSL https://ollama.com/install.sh | sh
systemctl status ollama --no-pager
ollama pull qwen3-coder:30b
ollama ls

Installer thêm một systemd unit và khởi động unit đó, nên systemctl status ollama phải in ra active (running). Nếu không, journalctl -e -u ollama sẽ in ra lý do.

Model phải hỗ trợ tool calling, vì agent hoạt động bằng cách gọi tool. Agent đọc một file, ghi một patch, chạy test, rồi đọc lỗi và thử lại. Model không thể phát ra tool call sẽ mô tả thay đổi bằng văn bản thay vì thực hiện thay đổi, khiến agent lặp vô hạn hoặc dừng lại. Trước khi pull, hãy tìm nhãn tools trên trang của model tại ollama.com. qwen3-coder:30b có nhãn này. Tính đến tháng 10 năm 2026, tag đó là bản tải xuống 19 GB với context window 256K. Nếu máy của bạn chỉ chạy bằng CPU hoặc có ít RAM, phần tính bộ nhớ cho tag Qwen 27B trên VPS cho biết cấu hình nào thực sự vừa với 8 đến 64 GB trước khi bạn tốn dung lượng tải xuống. Sau khi pull, số gigabyte đó sẽ nằm trên root disk của server. Đây thường là phần có ít dung lượng trống nhất trên VPS, vì vậy bạn nên đọc Ollama lưu các model file ở đâu và cách chuyển chúng sang nơi khác trước khi disk đầy.

Bây giờ hãy xác nhận server thực sự cung cấp những tên nào:

curl http://localhost:11434/v1/models

Các chuỗi trong response đó phải được ghi vào agent config chính xác từng ký tự. Kiểm tra trước như vậy sẽ xử lý được phần lớn lỗi model-not-found. Nếu Ollama chưa được cài, hãy xem hướng dẫn đầy đủ hơn tại tự host LLM bằng Ollama trên VPS.

Trỏ OpenCode đến Ollama

Chỉnh sửa ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "qwen3-coder:30b": {
          "name": "qwen3-coder 30b"
        }
      }
    }
  }
}

Key trong models là tên model được gửi đến Ollama, nên phải khớp chính xác với ollama ls. Trường name chỉ là nhãn hiển thị trong model picker. Khởi động opencode, chuyển sang Ollama provider và theo dõi journalctl -e -u ollama để xác nhận request đã đến server của bạn, thay vì đến một nơi khác. Phần thiết lập agent được trình bày trong chạy OpenCode trên VPS.

Trỏ Claude Code đến Ollama

export ANTHROPIC_AUTH_TOKEN=ollama
export ANTHROPIC_API_KEY=""
export ANTHROPIC_BASE_URL=http://localhost:11434
claude --model qwen3-coder:30b

ANTHROPIC_API_KEY được đặt thành chuỗi rỗng có chủ đích. Base URL quyết định nơi các request được gửi đến; xóa giá trị này giúp không đưa credential của dịch vụ hosted vào thiết lập local. ollama launch claude tự động cấu hình tất cả các thiết lập này.

Bạn cần biết compatibility layer không hỗ trợ những gì. Nó không triển khai tool_choice hoặc prompt caching, và không có endpoint đếm token. Vì vậy, số token bạn thấy chỉ là giá trị xấp xỉ dựa trên tokenizer của chính model. Claude Code cũng gửi kèm system prompt lớn và bộ tool lớn, nên cần nhiều context hơn chat client. Phần bạn có thể tự host Claude hay không đề cập đầy đủ hơn đến những gì được giữ lại và những gì không được giữ lại.

Trỏ Aider đến Ollama

export OLLAMA_API_BASE=http://127.0.0.1:11434
aider --model ollama_chat/qwen3-coder:30b

Tài liệu của Aider khuyến nghị dùng tiền tố ollama_chat/ thay cho ollama/. Theo mặc định, Aider yêu cầu đủ context cho mỗi request, cộng thêm 8k token cho phần trả lời. Aider cũng cho phép cố định context window cho từng model trong .aider.model.settings.yml. Tính năng này hữu ích khi một model cần context window khác với mặc định của server:

- name: ollama_chat/qwen3-coder:30b
  extra_params:
    num_ctx: 65536

Vì sao cấu hình vẫn chạy nhưng kết quả lại vô nghĩa

Đây là phần quan trọng. Ollama chọn độ dài context mặc định dựa trên tổng VRAM (bộ nhớ video trên các GPU) mà nó phát hiện được, rồi trừ OLLAMA_GPU_OVERHEAD cho mỗi GPU được phát hiện. Implementation sử dụng các ngưỡng sau:

[
  {
    "label": "Under 23 GiB aggregate VRAM",
    "default_context_tokens": "4,096"
  },
  {
    "label": "23 to under 47 GiB aggregate VRAM",
    "default_context_tokens": "32,768"
  },
  {
    "label": "47 GiB aggregate VRAM or more",
    "default_context_tokens": "262,144"
  }
]

Hầu hết VPS và mọi server chỉ dùng CPU đều nằm ở hàng đầu tiên: 4,096 token. Nhiều GPU nhỏ có thể cộng lại để đạt ngưỡng 47 GiB, tương ứng với 262,144 token ở hàng cuối.

Một agent truyền 4096 token trước khi bắt đầu xử lý. System prompt, định nghĩa tool, danh sách repository và file đầu tiên nó mở đã lớn hơn mức đó. Vấn đề xảy ra sau đó: không có lỗi nào xuất hiện. Tài liệu của Aider cho biết Ollama âm thầm loại bỏ phần context vượt quá cửa sổ. Các token cũ nhất bị loại khỏi context, vì vậy model trả lời rất tự tin về một file mà nó không còn nhìn thấy, hoặc quên mất một chỉ dẫn bạn đưa ra từ hai bước trước. Cơ chế này đứng sau phần lớn báo cáo rằng model local quá kém để viết code. Việc chọn con số này là một quyết định riêng, và chi phí của num_ctx trong KV cache memory ở từng kích thước đáng để đọc trước khi bạn chốt giá trị.

Tài liệu của Ollama cho biết các tác vụ như agent và coding tool nên được đặt tối thiểu ở 64000 token. Đặt giá trị này trên server:

sudo systemctl edit ollama.service

Thêm các dòng sau vào file override:

[Service]
Environment="OLLAMA_CONTEXT_LENGTH=64000"

Sau đó reload và restart:

sudo systemctl daemon-reload
sudo systemctl restart ollama
ollama ps

Gửi một request từ agent sau khi restart, rồi chạy lại ollama ps để có một model đã được load để kiểm tra. ollama ps là lệnh kiểm tra. Lệnh này in ra cột CONTEXT, và con số đó là lượng context model thực sự nhận được. ID và SIZE của bạn sẽ khác:

NAME               ID              SIZE     PROCESSOR    CONTEXT    UNTIL
qwen3-coder:30b    a1b2c3d4e5f6    24 GB    100% GPU     64000      4 minutes from now

Hãy đặt giá trị này trên server thay vì trong agent vì 2 lý do. OpenAI chat completions schema không có field cho độ dài context, nên client tương thích với OpenAI không thể yêu cầu giá trị này. Ngoài ra, setting này áp dụng cho từng server, nên mọi agent kết nối đến server đều kế thừa nó. Phía output có giới hạn riêng. Khác với độ dài context, giới hạn này được truyền qua compatibility endpoint, vì vậy num_predict và field max_tokens ánh xạ tới nó là các tùy chọn cần dùng khi reply dừng giữa chừng trong một patch. Nếu một model cần cửa sổ khác, hãy đóng gói nó thành một bản copy bằng Modelfile:

FROM qwen3-coder:30b
PARAMETER num_ctx 65536

ollama create qwen3-coder-64k -f Modelfile

Context không miễn phí. Cửa sổ dài hơn tốn nhiều memory hơn, vì vậy hãy theo dõi cột PROCESSOR. 100% GPU là giá trị bạn cần quan tâm. Khi một phần model bị đẩy sang CPU, tốc độ token giảm đủ nhiều để vòng lặp của agent trở nên không thể sử dụng. Đo tốc độ token mỗi giây trên một LLM local là cách xác định giới hạn thực tế của server. Việc tính toán cấu hình máy trước khi mua được trình bày trong mức RAM và CPU mà một coding agent VPS cần.

Giữ model đã nạp giữa các request

Theo mặc định, Ollama unload model sau 5 phút kể từ request cuối cùng. Thiết lập này phù hợp với hộp chat nhưng không phù hợp khi chạy agent. Bạn tạm dừng để đọc diff, timer hết hạn, rồi request tiếp theo phải nạp lại hàng chục gigabyte weights từ disk trước khi token đầu tiên xuất hiện. Hiện tượng này trông giống như bị treo.

OLLAMA_KEEP_ALIVE nhận chuỗi thời lượng như 10m hoặc 24h, một số nguyên biểu thị số giây, -1 để giữ model đã nạp vô thời hạn, hoặc 0 để unload ngay lập tức. Đặt tùy chọn này cạnh context length:

[Service]
Environment="OLLAMA_CONTEXT_LENGTH=64000"
Environment="OLLAMA_KEEP_ALIVE=-1"

Trường request keep_alive có trên các endpoint native /api/generate và /api/chat của Ollama, cũng như trên /v1/chat/completions dưới dạng phần mở rộng của Ollama. Agent có hỗ trợ các trường request bổ sung có thể gửi trường này tại đó; nếu không, hãy dùng biến môi trường. Khi cần giải phóng memory, ollama stop qwen3-coder:30b sẽ unload model mà không dừng server. Nếu muốn thiết lập này vẫn giữ nguyên sau reboot, hoặc muốn cân nhắc việc giữ weights trong memory cả ngày so với việc lấy lại phần memory đó, giữ model Ollama đã nạp trong memory hỗ trợ cả hai cách.

Chạy Ollama trên một máy chủ riêng

Ollama bind vào localhost. Để truy cập từ một máy khác, đặt OLLAMA_HOST=0.0.0.0:11434 trong cùng systemd override rồi restart service.

Chỉ làm vậy trên một mạng riêng. Tài liệu của Ollama cho biết local API không yêu cầu authentication, nên nếu mở port 11434 ra Internet thì bất kỳ ai cũng có thể sử dụng phần cứng của bạn. Có 2 phương án an toàn. Giữ bind ở localhost và forward port qua SSH từ laptop:

ssh -N -L 11434:localhost:11434 you@your-vps

Agent của bạn vẫn trỏ đến http://localhost:11434/v1 và không nhận biết sự khác biệt. Phương án còn lại là dùng VPN, với Ollama bind vào địa chỉ VPN thay vì 0.0.0.0. Nếu nhiều người hoặc nhiều agent cùng dùng một máy, Ollama hỗ trợ các request song song khi còn đủ memory, và phần so sánh giữa Ollama và vLLM cho thấy từ đâu chênh lệch throughput bắt đầu trở thành vấn đề.

Khi model coding chạy local chiếm ưu thế, và khi không

Agent sử dụng model do bạn tự host không thay thế được frontier API trong mọi tác vụ. Nó đặc biệt phù hợp với 4 loại công việc.

• Các chỉnh sửa cơ học hàng loạt, trong đó mỗi thay đổi nhỏ và bạn có thể kiểm tra. Đổi tên trên toàn repository, thêm type hint, viết docstring, dịch comment. Model có thể chạy hàng giờ mà chi phí không tăng.
• Công việc không được phép rời khỏi phần cứng của bạn. Ví dụ, code của khách hàng thuộc thỏa thuận bảo mật, hoặc repository nội bộ mà bạn không được phép gửi cho bên thứ ba.
• Máy offline và air-gapped, nơi hoàn toàn không có hosted API để gọi.
• Chi phí có thể dự đoán. Sau khi đã trả tiền cho server, một agent liên tục đốt token trong vòng lặp không phát sinh thêm chi phí. Điều này ngược lại với API tính phí theo mức sử dụng. Khi GPU VPS hòa vốn so với token API có phần tính toán cụ thể.

Nó kém hiệu quả với các tác vụ dài gồm nhiều bước. “Tìm nguyên nhân khiến test fail, sửa nguyên nhân đó, cập nhật các caller” cần nhiều tool call liên tiếp phải chính xác, đồng thời toàn bộ lịch sử vẫn phải nằm trong context. Model thuộc nhóm 8B đến 14B chạy trên server cấu hình vừa phải có thể tạo tool call sai định dạng hoặc mất kế hoạch sau vài lượt. Khi đó, bạn mất nhiều thời gian điều khiển nó hơn thời gian cần để tự làm tác vụ. Đây không phải vấn đề prompt có thể giải quyết bằng cách viết prompt tốt hơn. Đây là giới hạn về capacity.

Nó cũng kém phù hợp khi sai sót gây hậu quả lớn và bạn sẽ không đọc từng dòng. Hãy giao cho local model các công việc hẹp có output để bạn kiểm tra, còn những việc bạn không thể kiểm tra từng bước thì nên dùng hosted model.

Các tình huống lỗi và chuỗi bạn sẽ thấy

curl: (7) Failed to connect to localhost port 11434 after 0 ms: Connection refused. Server chưa chạy hoặc agent đang trỏ đến host khác. Chạy systemctl status ollama, sau đó chạy journalctl -e -u ollama.

Agent báo model không tồn tại. Tên trong config không khớp với tên mà server cung cấp. Đối chiếu với curl http://localhost:11434/v1/models và sao chép chuỗi từ đó. Tag là một phần của tên, vì vậy config chỉ định tag mà bạn chưa pull sẽ fail dù đã cài một model tương tự.

Agent trả lời bằng văn xuôi và không bao giờ sửa file. Model có thể không hỗ trợ tool, hoặc request cùng các định nghĩa tool đã chiếm hết context window. Kiểm tra nhãn tools trên trang model, sau đó kiểm tra cột CONTEXT trong ollama ps.

Im lặng lâu trước token đầu tiên, sau đó tốc độ bình thường. Keep-alive đã hết hạn và weights đang được đọc lại từ disk. Đặt OLLAMA_KEEP_ALIVE.

Model mâu thuẫn với file mà nó vừa đọc. Context bị truncate. ollama ps thường hiển thị giá trị CONTEXT nhỏ hơn mức bạn nghĩ đã đặt, vì biến môi trường được đặt trong shell thay vì trong systemd unit.

Mọi thứ đều hoạt động nhưng chậm, và PROCESSOR không phải 100% GPU. Thông thường, model cùng context của nó không vừa trong VRAM. Nếu PROCESSOR hiển thị 100% CPU trên máy có GPU, hãy loại trừ nguyên nhân còn lại trước: Ollama có thể hoàn toàn không phát hiện được GPU. Tài liệu của Ollama lưu ý rằng trên Linux, sau một chu kỳ suspend/resume, Ollama đôi khi không phát hiện được NVIDIA GPU và chuyển sang CPU; reload driver bằng sudo rmmod nvidia_uvm && sudo modprobe nvidia_uvm có thể khắc phục vấn đề này. Nếu đã phát hiện GPU nhưng việc phân bổ vẫn còn, hãy giảm độ dài context hoặc chuyển sang model nhỏ hơn hay quantisation nhỏ hơn. Trước khi pull lại, q4_K_M, q8_0 và fp16 tốn bao nhiêu memory, chất lượng thực sự giảm ở đâu sẽ cho biết việc giảm một bậc giúp có thêm bao nhiêu dung lượng và bạn phải đánh đổi những gì.

FAQ

Tôi có thể trỏ Claude Code vào Ollama không?

Có, nhưng không dùng URL tương thích với OpenAI. Claude Code sử dụng Anthropic Messages API, còn Ollama cung cấp định dạng đó tại /v1/messages trên cùng cổng 11434. Export ANTHROPIC_BASE_URL=http://localhost:11434, ANTHROPIC_AUTH_TOKEN=ollama và giá trị rỗng cho ANTHROPIC_API_KEY, rồi khởi động bằng claude --model qwen3-coder:30b. ollama launch claude sẽ ghi các thiết lập tương tự giúp bạn. Lớp tương thích này không triển khai tool_choice hoặc prompt caching, và không có endpoint đếm token, nên số token được báo chỉ là giá trị xấp xỉ.

Tại sao model local trả lời về đoạn code mà nó không thể nhìn thấy?

Vì request không còn vừa với context window, nên phần cũ nhất đã bị loại bỏ mà không báo lỗi. Ollama đặt context mặc định dựa trên tổng VRAM được phát hiện sau khi trừ phần overhead đã cấu hình cho mỗi GPU: dưới 23 GiB, mặc định là 4,096 token; từ 23 đến dưới 47 GiB là 32,768 token; và từ 47 GiB trở lên là 262,144 token. Đặt OLLAMA_CONTEXT_LENGTH=64000 trong systemd unit, restart Ollama, rồi xác nhận cột CONTEXT trong ollama ps hiển thị giá trị mới.

Tôi nên chạy model nào cho coding agent trên VPS?

Chọn model lớn nhất có nhãn tools nhưng vẫn vừa bộ nhớ khi dùng context window 64k, đồng thời ưu tiên model được tối ưu cho code. qwen3-coder:30b là lựa chọn phổ biến trên GPU server có đủ VRAM. Nếu tag đó quá lớn đối với server của bạn, các mức RAM và tốc độ chỉ dùng CPU của Nemotron 3.5 Lightning là thông tin so sánh hữu ích trước khi bạn tải model. Với model dưới khoảng 14B parameter, model vẫn có thể trả lời tốt các câu hỏi về code nhưng vẫn thất bại khi thực hiện chỉnh sửa nhiều bước, vì agent rất dễ hỏng do các lỗi định dạng nhỏ trong tool call. Hãy kiểm thử bằng một task thật trong repository của bạn thay vì sample prompt.

Tôi có cần GPU để chạy coding agent trên model của riêng mình không?

Trong thực tế là có. Inference chỉ dùng CPU vẫn hoạt động và phù hợp với các câu hỏi đơn lẻ, nhưng agent gửi nhiều request cho mỗi task và mỗi request lại đọc lại history dài, nên token rate thấp có thể biến task mất hai phút thành một giờ. Kiểm tra cột PROCESSOR trong ollama ps: mọi giá trị khác 100% GPU đều có nghĩa là một phần model đang chạy trên CPU, khiến token rate giảm mạnh.