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

Bạn đang kết nối đến đâu

Bạn có thể dùng Ollama với coding agent. Kết nối này đơ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 model name. Trường API key vẫn yêu cầu một giá trị, nhưng local server 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 phục vụ hai dạng request. /v1/chat/completions là dạng tương thích với OpenAI. Tài liệu của Ollama mô tả key ở đó là bắt buộc nhưng sẽ bị bỏ qua. /v1/messages là dạng tương thích với Anthropic, cũng là giao thức Claude Code sử dụng. Agent của bạn đã sử dụng một trong hai dạng này, nên không cần thay đổi phần nào khác.

Phần này chỉ mất năm phút. Kết quả có dùng được hay không phụ thuộc vào hai 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 loại tác vụ phù hợp với khả năng của nó. Mỗi setting sẽ có một section riêng. Các giới hạn thực tế được nêu ở cuối.

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ó tài liệu riêng về hỗ trợ Ollama. Danh sách này bao phủ phần lớn những gì mọi người gọi là coding agent vào tháng 8 năm 2026. Các công cụ này không dùng cùng một giao thức, và khác biệt đó là nguyên nhân khiến nhiều cấu hình 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à một chuỗi API key bất kỳ nhưng không được rỗng.
• 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, tại đó Ollama cung cấp /v1/messages.
• Codex dùng OpenAI Responses API. Ollama cũng cung cấp /v1/responses, bắt đầu 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. Thay vào đó, hãy đặt một translation layer phía trước, chẳng hạn như LiteLLM gateway tự host, rồi cung cấp lại model theo đúng định dạng mà client yêu cầu.

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

Cài 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 nguyên nhân.

Model phải hỗ trợ tool calling, vì agent hoạt động thông qua tool calling. Agent đọc một file, ghi 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 lại hoặc dừng. Hãy tìm nhãn tools trên trang của model tại ollama.com trước khi pull. qwen3-coder:30b có nhãn này. Tính đến tháng 8 năm 2026, tag đó là bản download 19 GB với context window 256K. Nếu máy của bạn chỉ dùng CPU hoặc có ít RAM, phần tính dung lượng bộ nhớ cho tag Qwen 27B trên VPS cho biết cấu hình nào thực sự vừa trong 8 đến 64 GB trước khi bạn tốn dung lượng download. Sau khi pull, số gigabyte đó sẽ nằm trên root disk của server. Đây là phần trên VPS thường có ít dung lượng trống nhất, nên vị trí Ollama lưu model file và cách chuyển chúng sang nơi khác là nội dung nên đọc trước khi disk đầy.

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

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

Các string trong response đó là những gì agent config phải chứa, đúng từng ký tự. Kiểm tra trước thường giải quyết được hầu hết lỗi không tìm thấy model. Nếu Ollama chưa được cài, xem hướng dẫn đầy đủ hơn tại cách self-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ủ ý. Nếu để một key thật trong environment, request sẽ được gửi đến hosted API thay vì local inference. Bạn sẽ phát sinh chi phí và không chạy inference cục bộ. ollama launch claude tự động thiết lập toàn bộ các giá trị này.

Hãy nắm rõ những gì compatibility layer không hỗ trợ. 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 một system prompt lớn cùng bộ công cụ lớn, nên cần nhiều context hơn chat client. Phạm vi rộng hơn về những gì có thể chuyển sang và những gì không thể chuyển sang được trình bày trong khả năng self-host Claude.

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 prefix ollama_chat/ thay vì ollama/. Bạn cũng có thể ghim context window cho từng model trong .aider.model.settings.yml. Cách này hữu ích khi một model cần 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 hoạt động bình thường vẫn cho kết quả vô nghĩa

Đây là phần quan trọng. Ollama chọn context length mặc định dựa trên VRAM (bộ nhớ video trên GPU) mà nó nhận thấy, và các giá trị mặc định đó được công bố:

[
  {
    "label": "Under 24 GiB VRAM",
    "default_context_tokens": "4,096"
  },
  {
    "label": "24 to 48 GiB VRAM",
    "default_context_tokens": "32,768"
  },
  {
    "label": "48 GiB VRAM or more",
    "default_context_tokens": "262,144"
  }
]

Hầu hết gói VPS và mọi server chỉ dùng CPU đều rơi vào hàng đầu tiên: 4,096 token. Chỉ GPU lớn mới nhận được 262,144 token ở hàng cuối.

Một agent dùng 4096 token trước khi thực hiện bất kỳ công việc nào. 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 tiếp theo là: 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á window. Các token cũ nhất bị loại bỏ, nên model tự tin trả lời về một file mà nó không còn nhìn thấy, hoặc quên một chỉ dẫn bạn đưa ra chỉ 2 bước trước. Cơ chế này đứng sau phần lớn báo cáo cho rằng model chạy local quá kém để viết code. Tự chọn giá trị này là một quyết định riêng, và chi phí của num_ctx trong bộ nhớ KV cache ở từng kích thước là nội dung đáng đọc trước khi bạn chốt giá trị.

Tài liệu của Ollama nói rằng các tác vụ như agent và coding tool nên được đặt ít nhất ở mức 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

ollama ps là bước kiểm tra. Lệnh này in ra một cột CONTEXT, và con số đó là giá trị 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

Đặt giá trị này trên server thay vì trong agent vì 2 lý do. OpenAI chat completions schema không có field dành cho context length, 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 theo server, nên mọi agent mà bạn trỏ đến server đều kế thừa nó. Phần output có giới hạn riêng. Không giống context length, giới hạn này được truyền qua compatibility endpoint, vì vậy num_predict và field max_tokens ánh xạ vào nó là các giá trị cần dùng khi reply dừng giữa chừng trong một patch. Nếu một model cần window khác, hãy tạo bản sao và tích hợp giá trị đó bằng Modelfile:

FROM qwen3-coder:30b
PARAMETER num_ctx 65536

ollama create qwen3-coder-64k -f Modelfile

Context không miễn phí. Window 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. Khi một phần model bị đẩy sang CPU, tốc độ token giảm đủ mạnh khiến vòng lặp của agent không thể sử dụng được. Đo token mỗi giây trên LLM local là cách tìm giới hạn thực tế của server. Nội dung VPS cần bao nhiêu RAM và CPU cho coding agent trình bày cách sizing máy trước khi mua.

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

Mặc định, Ollama unload model sau 5 phút kể từ request cuối cùng. Cách này phù hợp với hộp chat nhưng không phù hợp với tác vụ agent. Bạn tạm dừng để đọc diff, bộ đếm thời gian 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 duration 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 biến này cùng với context length:

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

Field request keep_alive chỉ có trên các endpoint native /api/generate và /api/chat của Ollama, không có trên các endpoint tương thích. Vì vậy agent không thể đặt giá trị này cho từng request. Environment variable là cách duy nhất bạn có thể sử dụng. Khi cần giải phóng memory, ollama stop qwen3-coder:30b unload model mà không dừng server. Nếu muốn setting này vẫn được giữ 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 trường hợp.

Chạy Ollama trên một server riêng

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

Chỉ thực hiện việc này trên private network. Tài liệu của Ollama nêu rằng local API không yêu cầu authentication, nên nếu mở port 11434 ra Internet, bất kỳ ai cũng có thể sử dụng phần cứng của bạn và đọc mọi nội dung agent gửi đi. Có 2 lựa chọ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 ra sự khác biệt. Lựa chọn còn lại là dùng VPN, rồi bind Ollama 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, scheduler của Ollama không được thiết kế cho tải như vậy, và phần so sánh giữa Ollama và vLLM cho thấy khác biệt về throughput bắt đầu gây ảnh hưởng ở đâu.

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 dạng lỗi và các 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 rồi sao chép chuỗi từ đó. Tag là một phần của tên, nên config chỉ định một tag mà bạn chưa pull sẽ bị lỗi dù đã cài một model tương tự.

Agent trả lời bằng văn bản nhưng không bao giờ chỉnh sửa file. Model 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 của model, sau đó kiểm tra cột CONTEXT trong ollama ps.

Chờ 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. Thiết lập OLLAMA_KEEP_ALIVE.

Model mâu thuẫn với file mà nó vừa đọc. Context bị cắt ngắn. ollama ps thường hiển thị giá trị CONTEXT nhỏ hơn mức bạn nghĩ mình đã đặ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. Model cùng context không vừa trong VRAM. 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 ngốn bao nhiêu memory, chất lượng thực sự giảm ở đâu sẽ cho biết việc hạ một mức giúp thêm bao nhiêu dung lượng và bạn phải đánh đổi điều 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à một ANTHROPIC_API_KEY rỗng, 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ự cho bạn. Lớp tương thích này không triển khai tool_choice hoặc prompt caching, đồng thời 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 của tôi trả lời về đoạn code mà nó không nhìn thấy?

Vì request không còn vừa với context window, và phần cũ nhất đã bị loại bỏ mà không có lỗi. Ollama đặt context mặc định dựa trên VRAM mà nó phát hiện. Khi VRAM dưới 24 GiB, giá trị mặc định là 4,096 token. Chỉ riêng system prompt và định nghĩa tool của agent cũng đã vượt quá mức này. Đặ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.

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 đủ chỗ trong memory khi dùng context window 64k, và ư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 với server của bạn, các thông số RAM và tốc độ chỉ dùng CPU của Nemotron 3.5 Lightning là dữ liệu so sánh hữu ích trước khi bạn tải model. Với model có ít hơn 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ễ bị ảnh hưởng bởi các lỗi định dạng nhỏ trong tool call. Hãy kiểm thử bằng một task thực tế từ repository của bạn thay vì sample prompt.

Tôi có cần GPU để chạy coding agent với model của 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 đều phải đọc lại history dài. Vì vậy, tốc độ token thấp có thể biến một task kéo dài 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, và tốc độ token sẽ giảm mạnh.