如何让编程代理使用本地 Ollama 模型

连接到什么

您可以将 Ollama 与编码代理配合使用，连接配置比很多人预期的更简单。您只需修改一个基础 URL，并选择一个模型名称。API 密钥字段仍要求填写值，但本地服务器会忽略该值，因此可以填写任意字符串。

Ollama 监听端口 11434，并同时提供 3 个 API 接口。/api 是 Ollama 的原生 API。/v1 是 OpenAI 兼容层，其中涵盖多种格式：/v1/chat/completions、/v1/responses、/v1/completions、/v1/models 和 /v1/embeddings。Ollama 文档说明，该处的密钥字段虽然必填，但会被忽略。第三个接口兼容 Anthropic：客户端将 http://localhost:11434 作为基础 URL，并追加 /v1/messages；Claude Code 使用的就是这一接口。大多数代理使用 /v1/chat/completions，Codex 使用 /v1/responses，Claude Code 使用 /v1/messages。您的代理已经支持其中一种接口，因此无需修改其他配置。

这部分配置只需 5 分钟。最终是否可用，主要取决于两个几乎没人修改的设置：上下文长度和 keep-alive；同时也取决于是否让模型处理它擅长的工作。这两个设置各有一节，最后还会说明实际限制。

哪些编程代理接受本地 base URL

测试只有一个问题：工具是否提供 base URL 设置。如果提供，就可以连接到您的服务器。

Ollama 为 Claude Code、OpenCode、Codex、Cline、Roo Code、Zed、JetBrains IDE 和 VS Code 发布了集成页面。Aider 另行说明了对 Ollama 的支持。这涵盖了截至 2026 年 10 月通常所说的大多数编程代理。它们使用的接口格式并不完全相同，配置失败通常就是因为这个差异。

• 大多数代理需要兼容 OpenAI 的端点。将 base URL 设置为 http://localhost:11434/v1，并提供任意非空 API key 字符串。
• Claude Code 完全不接受 OpenAI base URL。它使用 Anthropic Messages API，因此需要将 ANTHROPIC_BASE_URL 设置为 http://localhost:11434，Ollama 会在该地址提供 /v1/messages。
• Codex 使用 OpenAI Responses API。Ollama 同样提供 /v1/responses，该功能从版本 0.13.3 开始加入。
• 没有 base URL 设置的代理无法重定向，因为端点已内置在客户端中。请在前面增加转换层，例如 自托管的 LiteLLM 网关，然后按照客户端要求的接口格式重新提供您的模型。

Ollama 可以为您写入这些配置。ollama launch opencode 会使用您选择的模型和内联配置启动 OpenCode，ollama launch claude 对 Claude Code 执行相同操作，ollama launch droid --config 只写入配置而不启动工具。

安装 Ollama 并拉取可调用工具的模型

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

安装程序会添加 systemd 单元并启动该服务，因此 systemctl status ollama 应输出 active (running)。如果没有输出，journalctl -e -u ollama 会显示原因。

模型必须支持工具调用，因为工具调用是代理运行的基础。代理会读取文件、写入补丁、运行测试，然后读取失败信息并再次尝试。无法生成工具调用的模型只会用文字描述应执行的修改，而不会实际执行修改，代理随后会陷入循环或停止。拉取模型前，请先在 ollama.com 的模型页面查找 tools 标签。qwen3-coder:30b 带有该标签；截至 October 2026，该标签对应 19 GB 的下载内容和 256K 的上下文窗口。如果服务器仅使用 CPU 或内存较少，请先查看 VPS 上 Qwen 27B 标签的内存计算，了解在下载前 8 到 64 GB 内存实际能容纳什么。拉取模型后，这些 GB 会占用服务器的 root 磁盘空间。VPS 中可用空间最少的通常就是该磁盘。因此，在磁盘耗尽前，建议阅读 Ollama 保存模型文件的位置，以及如何将其移到其他位置。

现在确认服务器实际提供哪些名称：

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

该响应中的字符串就是代理配置必须包含的内容，必须逐字符一致。先检查这些名称，可以解决大多数找不到模型的问题。如果尚未安装 Ollama，请参阅更完整的教程：在 VPS 上使用 Ollama 自托管 LLM。

将 OpenCode 指向 Ollama

编辑 ~/.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"
        }
      }
    }
  }
}

models 下的键是发送给 Ollama 的模型名称，因此必须与 ollama ls 完全一致。name 字段只是模型选择器中显示的标签。启动 opencode，切换到 Ollama 提供程序，并监控 journalctl -e -u ollama，确认请求已到达您的服务器，而不是发送到其他位置。代理本身的配置请参阅在 VPS 上运行 OpenCode。

将 Claude Code 指向 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 会被特意设置为空字符串。环境中如果保留真实密钥，请求就会发送到托管 API，而不是本地推理，最终产生费用且不会使用本地模型。ollama launch claude 会为您完成这些设置。

请了解兼容层不支持哪些功能。它不实现 tool_choice，也不支持提示缓存，并且没有 token 计数端点，因此您看到的 token 数量只是根据模型自身 tokenizer 得出的近似值。Claude Code 还会发送较大的系统提示和工具集，因此所需上下文比聊天客户端更多。关于哪些内容可以迁移、哪些内容无法迁移，请参阅是否可以自行托管 Claude。

将 Aider 指向 Ollama

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

Aider 文档建议使用 ollama_chat/ 前缀，而不是 ollama/。您还可以在 .aider.model.settings.yml 中为每个模型固定上下文窗口大小。当某个模型需要使用不同于服务器默认值的窗口时，这一功能很有用：

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

为什么配置正常仍会产生错误结果

这一节最关键。Ollama 会根据它检测到的 VRAM（GPU 上的视频内存）选择默认上下文长度，并公开了这些默认值：

[
  {
    "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"
  }
]

大多数 VPS 套餐以及所有仅使用 CPU 的服务器都会落在第一行：4,096 个 token。只有配备大容量 GPU 的服务器，才能使用最后一行中的 262,144 个 token。

Agent 在开始执行任何操作前就会传入 4096 个 token。系统提示词、工具定义、代码仓库列表和它打开的第一个文件，加起来通常已经超过这个大小。接下来就会出现问题：系统不会报错。Aider 文档说明，超过窗口大小的上下文会被 Ollama 静默丢弃。较早的 token 会被移出窗口，因此模型可能自信地回答一个它已经无法查看的文件，或者忘记你两步之前给出的指令。大多数“本地模型太笨，无法编写代码”的报告，背后都是这个机制。上下文长度本身也需要单独选择；在确定数值前，建议阅读每种大小的 num_ctx 会占用多少 KV cache 内存。

Ollama 文档指出，Agent 和代码工具等任务至少应设置为 64000 个 token。在服务器上设置：

sudo systemctl edit ollama.service

在 override 文件中加入以下行：

[Service]
Environment="OLLAMA_CONTEXT_LENGTH=64000"

然后重新加载并重启：

sudo systemctl daemon-reload
sudo systemctl restart ollama
ollama ps

ollama ps 用于验证设置是否生效。它会输出 CONTEXT 列，该数值就是模型实际收到的上下文长度。你的 ID 和 SIZE 会有所不同：

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

应在服务器上设置上下文长度，而不是在 Agent 中设置，原因有二。OpenAI chat completions schema 没有上下文长度字段，因此兼容 OpenAI 的客户端无法请求该参数。其次，这个设置按服务器生效，因此连接到该服务器的每个 Agent 都会继承它。输出长度有自己的上限。与上下文长度不同，输出长度会通过兼容端点传递，因此当回复在补丁中途停止时，应使用num_predict 以及映射到它的 max_tokens 字段。如果某个模型需要不同的窗口大小，可以使用 Modelfile 将设置写入一个副本：

FROM qwen3-coder:30b
PARAMETER num_ctx 65536

ollama create qwen3-coder-64k -f Modelfile

上下文不是免费的。窗口越长，占用的内存越多，因此请监控 PROCESSOR 列。你需要关注的是 100% GPU。模型的一部分一旦溢出到 CPU，token 生成速率就会大幅下降，Agent 循环也会变得无法使用。通过测量本地 LLM 的每秒 token 数，可以找出服务器的实际上限。购买服务器前如何评估硬件需求，请参阅编程 Agent VPS 需要多少 RAM 和 CPU。

在请求之间保持模型加载

默认情况下，Ollama 会在模型处理完最后一个请求 5 分钟后将其卸载。这适合聊天框，但不适合代理工作。您暂停查看差异，计时器耗尽，下一次请求就会从磁盘重新加载数十 GB 的权重，直到第一个 token 出现前都没有响应。这看起来像是服务挂起。

OLLAMA_KEEP_ALIVE 接受持续时间字符串，例如 10m 或 24h；也接受表示秒数的普通数字、用于无限保持模型加载的 -1，以及用于立即卸载模型的 0。将其与上下文长度放在一起设置：

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

keep_alive 请求字段仅存在于 Ollama 原生的 /api/generate 和 /api/chat 端点，不适用于兼容性端点，因此代理无法为每个请求单独设置该字段。环境变量是您唯一可用的控制方式。需要释放内存时，ollama stop qwen3-coder:30b 会卸载模型，但不会停止服务器。如果希望该设置在重启后仍然生效，或希望权衡全天将权重保留在内存中与释放这些内存之间的取舍，请参阅 让 Ollama 模型保持加载在内存中。

在单独的服务器上运行 Ollama

Ollama 绑定到 localhost。要从另一台计算机访问它，请在同一个 systemd override 中设置 OLLAMA_HOST=0.0.0.0:11434，然后重启服务。

仅在私有网络中执行此操作。Ollama 文档说明，本地 API 不需要身份验证。因此，如果端口 11434 对互联网开放，任何人都可以使用您的硬件，并读取代理发送的所有内容。有两种安全方案。将绑定地址保留为 localhost，然后从笔记本电脑通过 SSH 转发端口：

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

您的代理继续指向 http://localhost:11434/v1，完全无需感知这一变化。另一种方案是使用 VPN，让 Ollama 绑定到 VPN 地址，而不是 0.0.0.0。如果多个人或多个代理要共用一台服务器，Ollama 的调度器并不是为这种负载设计的；Ollama 与 vLLM 的对比说明了吞吐量差异从何处开始造成影响。

本地代码模型在哪些方面占优，在哪些方面不占优

由您自行托管的模型驱动的代理，并不能在所有任务上替代前沿 API。它在以下四类工作中具有明显优势。

• 批量机械式修改。每次修改都很小，并且可以检查。例如，在整个代码仓库中重命名、添加类型提示、编写文档字符串、翻译注释。模型可以运行数小时，而费用不会增加。
• 不能离开本地硬件的工作。例如，受保密协议约束的客户端代码，或不允许发送给第三方的内部代码仓库。
• 离线和物理隔离的计算机。这类环境根本没有可调用的托管 API。
• 成本可预测。服务器成本支付完毕后，代理即使循环消耗 token，也不会产生额外费用；这与按用量计费的 API 正好相反。GPU VPS 与 API token 达到成本平衡的位置中给出了计算过程。

它在长流程、多步骤任务上处于劣势。“找出这个测试失败的原因、修复根因、更新调用方”需要连续执行许多正确的工具调用，并且整个历史记录都要保留在上下文中。在配置一般的服务器上，8B 到 14B 范围内的模型可能会生成格式错误的工具调用，或者在几轮交互后丢失计划。您花在引导模型上的时间，可能比手动完成任务还多。这不是可以通过编写更好的提示来解决的问题，而是模型容量的问题。

当出错代价较高，且您不会逐行检查输出时，本地模型同样处于劣势。应为本地模型安排范围明确、输出可验证的任务；对于不会逐步检查的工作，则继续使用托管模型。

故障模式及你将看到的字符串

curl: (7) Failed to connect to localhost port 11434 after 0 ms: Connection refused。 服务器未运行，或 agent 指向了其他主机。运行 systemctl status ollama，然后运行 journalctl -e -u ollama。

agent 报告模型不存在。 配置中的名称与服务器提供的名称不匹配。将其与 curl http://localhost:11434/v1/models 进行比较，并从那里复制字符串。标签也是名称的一部分，因此，如果配置指定了从未拉取的标签，即使已安装名称相近的模型，也会失败。

agent 使用自然语言回答，且从不编辑文件。 模型可能不支持工具，或者请求及其工具定义已经占满上下文窗口。检查模型页面上的 tools 标签，然后检查 ollama ps 中的 CONTEXT 列。

第一个 token 出现前长时间无响应，随后速度正常。 keep-alive 已过期，系统正在重新从磁盘读取权重。设置 OLLAMA_KEEP_ALIVE。

模型否定了它刚刚读取的文件内容。 这是上下文截断。ollama ps 通常会显示一个小于预期的 CONTEXT 值，因为环境变量被设置到了你的 shell，而不是 systemd 单元。

所有功能都正常，但速度很慢，并且 PROCESSOR 不是 100% GPU。 通常是模型及其上下文无法装入 VRAM。如果在配有 GPU 的机器上，PROCESSOR 显示为 100% CPU，应先排除另一种原因：Ollama 可能根本没有找到 GPU。Ollama 文档指出，在 Linux 上，系统挂起并恢复后，有时无法发现 NVIDIA GPU，因而会回退到 CPU；使用 sudo rmmod nvidia_uvm && sudo modprobe nvidia_uvm 重新加载驱动可以绕过此问题。如果已找到 GPU，但仍然发生拆分，请降低上下文长度，或改用更小的模型或更小的量化版本。重新拉取模型前，请先阅读q4_K_M、q8_0 和 fp16 各自占用多少内存，以及质量实际在哪里下降，了解降低一个级别能释放多少空间，以及需要为此放弃什么。

FAQ

我可以让 Claude Code 连接 Ollama 吗？

可以，但不能使用 OpenAI 兼容 URL。Claude Code 使用 Anthropic Messages API，而 Ollama 在同一 11434 端口的 /v1/messages 提供这种接口格式。导出 ANTHROPIC_BASE_URL=http://localhost:11434、ANTHROPIC_AUTH_TOKEN=ollama 和空的 ANTHROPIC_API_KEY，然后使用 claude --model qwen3-coder:30b 启动。ollama launch claude 会为您写入相同的设置。兼容层不实现 tool_choice 或提示缓存，也没有 token 计数端点，因此报告的 token 数量只是近似值。

为什么我的本地模型会回答它看不到的代码？

因为请求已超出上下文窗口，最早的部分会被丢弃，而且不会显示错误。Ollama 会根据检测到的 VRAM 设置默认上下文；当 VRAM 小于 24 GiB 时，默认值为 4,096 tokens，仅 agent 的系统提示和工具定义就会超过该值。在 systemd unit 中设置 OLLAMA_CONTEXT_LENGTH=64000，重启 Ollama，然后确认 ollama ps 的 CONTEXT 列显示新值。

在 VPS 上运行编码 agent 应该选择哪个模型？

选择带有 tools 标签且在 64k 上下文窗口下仍能装入内存的最大模型，并优先选择针对代码调优的模型。在 VRAM 充足的 GPU 服务器上，qwen3-coder:30b 通常是常见选择。如果该标签对应的模型对您的服务器来说太大，可以先参考Nemotron 3.5 Lightning 的 RAM 数据和仅使用 CPU 时的速度，再决定是否下载。参数量低于约 14B 时，模型仍可能很好地回答代码问题，但在执行多步骤编辑时失败，因为 agent 任务对工具调用中的细小格式错误非常敏感。请使用您自己代码仓库中的一个真实任务进行测试，不要只使用示例提示。

我需要 GPU 才能在自己的模型上运行编码 agent 吗？

实际上需要。仅使用 CPU 推理可以运行，处理单个问题也没有问题，但 agent 每个任务会发送许多请求，而且每次都会重新读取较长的历史记录。因此，较低的 token 速率会把一个两分钟的任务变成一小时。检查 ollama ps 中的 PROCESSOR 列：任何不是 100% GPU 的值都表示部分模型在 CPU 上运行，token 速率会明显下降。