作者： Matt Connor
如何将 Ollama 接入编码代理
配置 Ollama 编码代理只需修改基础 URL，但需注意 11434 端口、任意 API key、Claude Code 的 Anthropic 端点，以及 Codex 需 Ollama 0.13.3+ 支持 Responses API。
连接方式
您可以将 Ollama 与编码代理配合使用，连接配置比预期更简单。您只需修改一个基础 URL，并选择一个模型名称。API key 字段仍要求填写值，但本地服务器会忽略该值，因此可以填写任意字符串。
Ollama 监听 11434 端口，同时提供两种请求格式。/v1/chat/completions 是 OpenAI 兼容格式。Ollama 文档将其中的 key 标记为必填项，但该值会被忽略。/v1/messages 是 Anthropic 兼容格式，Claude Code 使用这种格式。您的代理已经支持其中一种格式，因此其他配置无需修改。
完成这部分只需 5 分钟。实际效果是否可用，取决于两个几乎没人修改的设置：上下文长度和 keep-alive；同时也取决于让模型执行它擅长的工作。这两个设置分别有独立章节，最后还会说明实际限制。
哪些编码代理支持本地 base URL
测试只有一个问题：工具是否提供 base URL 设置。如果提供，就可以连接到您的服务器。
Ollama 为 Claude Code、OpenCode、Codex、Cline、Roo Code、Zed、JetBrains IDE 和 VS Code 发布了集成页面。Aider 另行记录了对 Ollama 的支持。这涵盖了截至 2026 年 8 月人们通常所说的大多数编码代理。但它们使用的接口格式并不相同，这正是配置失败的原因。
- 大多数代理需要 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 带有该标签；截至 August 2026，该标签对应的模型下载大小为 19 GB，上下文窗口为 256K。
现在确认服务器实际提供哪些名称：
curl http://localhost:11434/v1/models响应中的字符串就是代理配置必须包含的内容，字符必须完全一致。先检查这些名称，可以解决大多数 model-not-found 错误。如果尚未安装 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:30bANTHROPIC_API_KEY特意设置为空字符串。环境中如果保留真实密钥，请求就会改为发送到托管 API，产生费用，并且不会执行本地推理。ollama launch claude会为您完成所有这些设置。
请了解兼容层未实现的功能。它不支持 tool_choice 或提示缓存，也没有 token 计数端点，因此您看到的 token 数量只是根据模型自身分词器得出的近似值。Claude Code 还会发送较大的系统提示和工具集，因此需要的上下文多于聊天客户端。关于哪些功能可以迁移、哪些不能迁移，请参阅能否自行托管 Claude。
将 Aider 指向 Ollama
export OLLAMA_API_BASE=http://127.0.0.1:11434
aider --model ollama_chat/qwen3-coder:30bAider 文档建议使用 ollama_chat/ 前缀，而不是 ollama/。您还可以在 .aider.model.settings.yml 中为每个模型固定上下文窗口大小。当某个模型需要使用不同于服务器默认值的窗口大小时，这一功能很有用：
- name: ollama_chat/qwen3-coder:30b
extra_params:
num_ctx: 65536可用的配置为何仍然产生无意义的结果
这一节最重要。Ollama 会根据它检测到的 VRAM（GPU 上的视频内存）选择默认上下文长度，并公开了这些默认值：
The data behind this chart
[
{
"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。
代理在执行任何工作前就会传入 4096 个 token。系统提示、工具定义、仓库列表和它打开的第一个文件加起来，已经超过这个数量。接下来发生的事情正是问题所在：系统不会报错。Aider 文档说明，超过上下文窗口的内容会被 Ollama 静默丢弃。最早的 token 会被移出窗口，因此模型会自信地回答一个它已经无法看到的文件，或者忘记您两步之前给出的指令。这种机制是大多数“本地模型太笨，无法编写代码”报告的根源。
Ollama 文档建议，代理和编码工具等任务至少应设置为 64000 个 token。在服务器上设置：
sudo systemctl edit ollama.service在 override 文件中添加以下内容：
[Service]
Environment="OLLAMA_CONTEXT_LENGTH=64000"然后重新加载并重启：
sudo systemctl daemon-reload
sudo systemctl restart ollama
ollama psollama ps 用于检查结果。它会输出一个 CONTEXT 列，该数字就是模型实际收到的上下文长度。您的 ID 和 SIZE 会有所不同：
NAME ID SIZE PROCESSOR CONTEXT UNTIL
qwen3-coder:30b a1b2c3d4e5f6 24 GB 100% GPU 64000 4 minutes from now应在服务器上设置，而不是在代理中设置，原因有二。OpenAI chat completions schema 没有用于指定上下文长度的字段，因此兼容 OpenAI 的客户端无法请求特定长度。并且该设置针对整个服务器，因此连接到此服务器的每个代理都会继承它。如果某个模型需要不同的窗口，可以使用 Modelfile 创建一个副本，并将设置写入其中：
FROM qwen3-coder:30b
PARAMETER num_ctx 65536ollama create qwen3-coder-64k -f Modelfile上下文并不是免费的。窗口越长，消耗的内存越多，因此请监控 PROCESSOR 列。您需要关注 100% GPU。模型的一部分内容一旦溢出到 CPU，token 速率就会下降到代理循环无法使用的程度；通过测量本地 LLM 的每秒 token 数，可以找到服务器的实际上限。编码代理 VPS 需要多少 RAM 和 CPU介绍了购买服务器前如何评估机器配置。
在请求之间保持模型加载
默认情况下，Ollama 会在模型处理完最后一个请求 5 分钟后将其卸载。这个设置适合聊天框，但不适合代理工作。您暂停查看 diff 后，计时器到期；下一个请求必须先从磁盘重新加载数十 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 绑定到 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。降低上下文长度，或改用更小的模型或更小的量化版本。
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 个 token，而 agent 的系统提示词和工具定义本身就会超过这一大小。在 systemd 单元中设置 OLLAMA_CONTEXT_LENGTH=64000，重启 Ollama，然后确认 ollama ps 中的 CONTEXT 列显示了新值。
在 VPS 上运行 coding agent 时，应该使用哪个模型？
选择带有 tools 标签、在 64k 上下文窗口下仍能放入内存的最大模型，并优先选择针对代码调优的模型。在 VRAM 充足的 GPU 服务器上，通常使用 qwen3-coder:30b。参数量低于大约 14B 时，模型仍可能很好地回答代码问题，但在执行多步编辑时失败，因为 agent 任务中的工具调用无法容忍细小的格式错误。请使用自己代码仓库中的一个真实任务进行测试，不要只使用示例提示词。
要在自己的模型上运行 coding agent，必须使用 GPU 吗？
实际使用中，是的。仅使用 CPU 推理可以运行，也适合处理单个问题；但 agent 每项任务都会发送许多请求，而且每次都会重新读取较长的历史记录，因此较低的 token 速率会将一个两分钟的任务变成一小时。检查 ollama ps 中的 PROCESSOR 列：任何不是 100% GPU 的值，都表示模型的一部分正在 CPU 上运行，token 速率会大幅下降。