Dùng Ollama với coding agent: cấu hình và giới hạn

Bạn đang kết nối với gì

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 local server sẽ bỏ qua giá trị đó, nên dùng chuỗi nào cũng được.

Ollama lắng nghe trên port 11434 và đồng thời hỗ trợ 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 trong dạng này là bắt buộc nhưng bị bỏ qua. /v1/messages là dạng tương thích với Anthropic, cũng là dạng Claude Code sử dụng. Agent của bạn đã hỗ trợ 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ó sử dụng được hay không phụ thuộc vào hai thiết lập mà gần như không ai thay đổi: context length và keep-alive. Nó cũng phụ thuộc vào việc giao cho model đúng loại công việc mà model làm tốt. Mỗi thiết lập sẽ có một section riêng. Các giới hạn thực tế sẽ đượ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ỉ gồm 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 IDE và VS Code. Aider có tài liệu riêng về hỗ trợ Ollama. Các công cụ 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. Chúng không dùng cùng một định dạng API, và chính khác biệt này khiến các 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. Nó 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. Thay vào đó, hãy đặt một translation layer phía trước, chẳng hạn như gateway LiteLLM 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 cấu hình này cho bạn. ollama launch opencode khởi động OpenCode với cấu hình inline cho model bạn chọn, ollama launch claude thực hiện tương tự với Claude Code, còn ollama launch droid --config ghi cấu hình nhưng không khởi động 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

Trình cài đặt thêm một systemd unit và khởi động unit đó, vì vậy 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 patch, chạy test, đọc lỗi rồi thử lại. Model không thể phát ra tool call sẽ chỉ mô tả thay đổi bằng văn bản thay vì thực hiện thay đổi. Khi đó agent sẽ 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 August 2026, model đó yêu cầu tải xuống 19 GB và có context window 256K.

Bây giờ xác nhận các tên mà server thực sự cung cấp:

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

Các chuỗi trong phản hồi đó phải được ghi vào cấu hình agent chính xác từng ký tự. Kiểm tra trước sẽ giải quyết phần lớn lỗi không tìm thấy model. Nếu Ollama chưa được cài đặt, 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"
        }
      }
    }
  }
}

Giá trị 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 provider Ollama và monitor journalctl -e -u ollama để xác nhận request đã đến server của bạn thay vì 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 tới 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 cố ý đặt thành chuỗi rỗng. Nếu để một key thật trong environment, request sẽ được gửi tới API hosted thay vì API cục bộ, khiến bạn phát sinh chi phí và không chạy inference cục bộ. ollama launch claude tự động thiết lập tất cả phần này.

Bạn cần biết compatibility layer không hỗ trợ những gì. Layer này không implement tool_choice hoặc prompt caching, và không có endpoint đếm token. Vì vậy, số token hiển thị chỉ là giá trị xấp xỉ do tokenizer của model tự tính. Claude Code cũng đi kèm system prompt lớn và bộ công cụ lớn, nên cần nhiều context hơn chat client. Phần giải thích đầy đủ về những gì có thể chuyển sang và những gì không thể chuyển sang nằm trong khả năng bạn 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 tiền tố ollama_chat/ thay cho ollama/. Bạn cũng có thể cố định context window cho từng model trong .aider.model.settings.yml. Cách này hữu ích khi một model cần context window khác với giá trị 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 vẫn cho kết quả vô nghĩa

Đây là phần quan trọng. Ollama chọn độ dài context mặc định dựa trên VRAM (bộ nhớ video trên GPU) mà nó nhận diện được. 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 nằm ở 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 sử dụng 4096 token trước khi thực hiện bất kỳ tác vụ nào. System prompt, định nghĩa tool, danh sách repository và file đầu tiên nó mở đã lớn hơn giới hạn đó. Vấn đề xảy ra tiếp theo là: không có lỗi nào được báo. Tài liệu của Aider nêu rõ 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 bỏ. Vì vậy model vẫn trả lời một cách chắc chắn về file mà nó không còn nhìn thấy, hoặc quên một instruction 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.

Tài liệu của Ollama cho biết các tác vụ như agent và coding tool nên được đặt ở mức 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

ollama ps là lệnh kiểm tra. Lệnh này in ra một cột CONTEXT. Con số đó là lượng context model thực sự nhận được. Giá trị 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 theo server, nên mọi agent kết nối đến server đều kế thừa nó. Nếu một model cần cửa sổ khác, hãy đóng gói giá trị đó vào một bản sao 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 cầ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 tràn sang CPU, tốc độ sinh token giảm đủ nhiều để vòng lặp của agent không thể sử dụng được. Đo tốc độ token mỗi giây trên LLM local là cách tìm giới hạn thực tế của máy bạn. Cách xác định cấu hình máy trước khi mua được trình bày trong VPS cần bao nhiêu RAM và CPU cho coding agent.

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. 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ộ hẹn giờ hết hạn, rồi request tiếp theo phải nạp lại hàng chục gigabyte weight 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 biến này cùng với context length:

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

Trường 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. Biến môi trường là tùy chọn duy nhất bạn có. Khi cần giải phóng memory, ollama stop qwen3-coder:30b sẽ unload model mà không dừng server.

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 khởi động lại service.

Chỉ thực hiện việc này trên mạng riêng. Tài liệu của Ollama nêu rõ local API không yêu cầu xác thực, vì vậy nếu mở cổng 11434 ra Internet thì 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 trên localhost và chuyển tiếp cổng qua SSH từ laptop của bạn:

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 thấy khác biệt. Lựa chọ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 sẽ dùng chung một máy, scheduler của Ollama không được thiết kế cho tải này, và phần so sánh giữa Ollama và vLLM cho thấy sự chênh lệch throughput bắt đầu gây ảnh hưởng ở đâu.

Khi local coding model phát huy hiệu quả và khi không

Agent chạy bằng model do bạn tự host không thay thế được frontier API trong mọi tác vụ. Nó đặc biệt hiệu quả 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à có thể kiểm tra được. Đổ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 đã thanh toán server, agent chạy vòng lặp và tiêu token không làm phát sinh thêm chi phí. Điều này trái ngược 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ể.

Local model kém hiệu quả với các tác vụ dài gồm nhiều bước. Yêu cầu như “Tìm nguyên nhân test này fail, sửa nguyên nhân đó rồi cập nhật các caller” cần nhiều lần gọi tool chính xác liên tiếp, trong khi 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 quên 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 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.

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

Các dạ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 cấu hình 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, vì vậy cấu hình chỉ định 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 và không chỉnh sửa file. Model không hỗ trợ tool, hoặc request cùng các định nghĩa tool đã chiếm toàn bộ context window. Kiểm tra nhãn tools trên trang 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. Đặt OLLAMA_KEEP_ALIVE.

Model mâu thuẫn với file mà nó vừa đọc. Context bị cắt bớt. ollama ps thường hiển thị giá trị CONTEXT nhỏ hơn 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 của nó không vừa trong VRAM. Giảm context length, hoặc chuyển sang model nhỏ hơn hay quantisation nhỏ hơn.

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 giao diện đó 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, sau đó 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 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 cáo chỉ là giá trị xấp xỉ.

Vì sao model cục bộ trả lời về đoạn code mà nó không thể nhìn thấy?

Vì request không còn vừa trong 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 VRAM mà nó phát hiện. Khi VRAM dưới 24 GiB, mặc định này là 4,096 token, trong khi system prompt và định nghĩa tool của agent đã tự vượt quá mức đó. Đặt OLLAMA_CONTEXT_LENGTH=64000 trong systemd unit, khởi động lại 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 đủ 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. 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ễ bị ảnh hưởng bởi các lỗi định dạng nhỏ trong tool call. Hãy 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 trên 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 lại đọc lại một lịch sử dài. Vì vậy, tốc độ token thấp có thể biến task kéo dài 2 phút thành 1 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.