Ollama 配置代理：按系统设置 HTTPS_PROXY 并完成验证

更新于 2026-11-09 · a6api.cyou

简答：如果你的目标是让 Ollama 下载模型时经过代理，优先配置 HTTPS_PROXY，并在重启 Ollama 服务或应用后再执行 ollama pull；不要把“出站代理”和“把 11434 API 暴露出去的反向代理”混为一谈。最短路径是：设置代理变量→彻底重启 Ollama→用 ollama pull 或服务日志验证。

定义：Ollama 代理配置，是通过 HTTPS_PROXY 等环境变量让 Ollama 的出站 HTTPS 请求经过指定代理；它不同于用 Nginx、隧道或网关转发本地 Ollama API。

先判断你要配置哪一种代理

本文面向需要让 Ollama 下载模型或访问远端模型仓库的场景。Ollama 官方文档说明，模型拉取使用 HTTPS 请求，可以使用 HTTPS_PROXY 重定向出站请求；官方同时提醒不要随意设置 HTTP_PROXY，因为 Ollama 的模型拉取并不使用 HTTP，额外设置可能干扰客户端与服务端连接。Ollama 官方 FAQ

如果你的目标是让局域网内其他设备访问本机的 Ollama API，配置方向不同，通常涉及 OLLAMA_HOST 和反向代理。不要因为模型下载失败就直接把 11434 端口暴露到公网；先完成本机代理验证，再处理 API 转发和访问控制。

一张表看懂各平台的最短配置路径

当前 Ollama 源码将 HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY作为可读取的环境变量；非 Windows 系统还兼容小写形式。具体变量是否被进程继承，取决于你是从终端、桌面应用、systemd 还是容器启动 Ollama。Ollama 官方环境变量实现

Windows：设置环境变量并彻底重启 Ollama

1. 打开 Windows 的“环境变量”设置，在用户变量或系统变量中新增 HTTPS_PROXY，值填写你的代理地址，例如 http://127.0.0.1:端口。端口只使用你本机代理软件实际监听的端口，不要照抄示例数字。

2. 如果需要让本机地址或内网地址绕过代理，可按需设置 NO_PROXY，例如包含 localhost,127.0.0.1。不要把完整代理密码写进截图、工单或日志。

3. 保存后，从任务栏托盘菜单退出 Ollama，再重新启动。只修改环境变量而不重启已经运行的 Ollama 进程，通常不能让旧进程自动获得新变量。

4. 打开新的 PowerShell 窗口，执行 ollama pull 模型名。成功信号是下载流程继续推进并最终完成；如果仍失败，记录脱敏后的目标主机、HTTP 状态码、错误正文和时间，不要记录完整代理 URL。

如果你用的是命令行启动而不是桌面应用，也可以在启动前临时设置变量：$env:HTTPS_PROXY="http://127.0.0.1:端口"，再执行 ollama serve。这只适用于该 PowerShell 会话，不能据此判断桌面应用已经读取变量。

macOS：桌面应用与终端进程要分别处理

1. 先退出 Ollama 应用。若应用仍在运行，后续设置可能不会影响已经存在的服务进程。

2. 在终端中执行类似 launchctl setenv HTTPS_PROXY http://127.0.0.1:端口 的命令。请替换为实际代理地址；如果代理需要认证，优先使用系统的安全凭据管理方式或受保护的启动配置，避免把密码写进 shell 历史。

3. 重新打开 Ollama 应用，再执行 ollama pull 模型名。如果你只在当前终端执行 export HTTPS_PROXY=...，它通常只影响从该终端启动的子进程，不足以证明桌面应用已经使用代理。

4. 完成测试后，如需取消由 launchctl 注入的变量，可使用对应的环境变量删除操作，并再次重启应用。具体命令以当前 macOS 版本和 Ollama 安装方式为准。

macOS 上最常见的误判是“终端里变量存在，所以桌面应用一定能用”。实际排查应确认 Ollama 服务进程的启动方式，并用一次实际的模型拉取验证，而不是只查看终端中的变量。

Linux systemd：写入服务环境并重启

如果 Ollama 由 systemd 管理，建议把变量写入服务配置，而不是只在当前 shell 中执行 export。可以创建服务覆盖配置：

sudo systemctl edit ollama

在编辑器中加入：

[Service]
Environment="HTTPS_PROXY=http://127.0.0.1:端口"
Environment="NO_PROXY=localhost,127.0.0.1"

保存后依次执行：

sudo systemctl daemon-reload
sudo systemctl restart ollama
sudo systemctl status ollama --no-pager

如果服务启动失败，先检查代理地址格式、引号、端口和 systemd 配置语法。官方 FAQ 的核心建议是：systemd 运行方式需要把环境变量提供给服务本身；仅在登录用户的 shell 配置文件里设置变量，未必会传递给 systemd 服务。Ollama 官方 FAQ

验证时执行 ollama pull 模型名，并通过 journalctl -u ollama 查看服务日志。日志中只保留必要的错误信息；代理认证信息、完整请求 URL 和 API Key 不应进入日志。

Docker：在创建容器时传入 HTTPS_PROXY

Ollama 官方 FAQ 给出的 Docker 方向是，在启动容器时通过 -e HTTPS_PROXY=... 传入代理变量。示例结构如下：

docker run -d --name ollama -e HTTPS_PROXY=http://host.docker.internal:端口 ollama/ollama

上面的镜像名和代理地址只是命令结构示例，实际镜像标签、网络模式和宿主机访问地址应以你的部署方式为准。不要把带密码的完整代理 URL 直接提交到脚本仓库。

1. 先停止并删除旧容器，或使用新的容器名重新创建。

2. 在 docker run 或编排文件中加入 HTTPS_PROXY；若需要绕过本地地址，再加入 NO_PROXY。

3. 使用 docker inspect 容器名 检查变量是否已注入，但输出分享前要脱敏。

4. 进入容器或从宿主机执行模型拉取测试，确认请求确实能继续。

如果代理使用 HTTPS 且证书由内部 CA 签发，官方文档要求将相应证书安装为系统证书；仅把代理地址改成 https:// 并不能自动解决证书信任问题。Ollama 官方 Docker 与证书说明

最小验证闭环：不要只看变量有没有值

1. 确认最终进程：先判断 Ollama 是桌面应用、终端进程、systemd 服务还是 Docker 容器。变量设置在错误的启动层，配置就不会生效。

2. 确认最终变量：查看对应进程或容器是否获得 HTTPS_PROXY。查看时只显示主机和端口，代理用户名和密码必须脱敏。

3. 确认真实请求：执行 ollama pull 模型名，观察是否从连接失败转为下载或完成。不要仅用普通 curl 测试代替 Ollama 测试，因为两个进程可能读取不同的环境变量。

4. 确认日志：Linux 查看 journalctl -u ollama，Docker 查看 docker logs 容器名，桌面应用则查看应用提供的日志位置。记录时间、目标主机、状态码、错误正文和 request-id（如果有），不要记录完整密钥或代理密码。

如果你需要确认代理本身是否可用，可以在不暴露凭据的前提下，用代理软件或系统网络工具测试目标 HTTPS 主机；但最终判断仍应回到 Ollama 进程的实际模型拉取结果。

错误分流：按最终主机、认证和响应体排查

这张表是通用诊断方向，不代表每个代理或部署都会返回相同错误码。最终应以实际响应正文、服务日志和当前 Ollama 文档为准。

代理认证、证书和安全边界

• 代理地址包含用户名或密码时，不要把完整 URL 放进公开脚本、命令历史、截图、工单或日志。可以使用受保护的环境文件、系统凭据管理或容器密钥机制，并限制文件权限。

• 如果密码包含 @、:、#、空格等特殊字符，URL 编码和 shell 转义都可能影响解析。遇到认证失败时，先用不含敏感信息的临时凭据或安全配置文件验证格式。

• HTTPS 代理的证书链必须被运行 Ollama 的系统或容器信任。不要用关闭 TLS 校验的方式“修复”证书错误。

• HTTPS_PROXY解决的是 Ollama 发出的出站请求；它不会自动为 Ollama API 增加登录认证，也不会替你安全暴露 11434 端口。

• 如果要通过 Nginx 等反向代理访问 Ollama，必须另外配置访问控制、TLS 和网络边界。官方 FAQ 提供了反向代理方向，但不等于可以无鉴权公开服务。Ollama 官方网络暴露说明

推荐的排查顺序

把问题压缩成下面七步，通常比反复更换代理地址更有效：

1. 确认目标是下载模型，还是转发本地 API。

2. 确认 Ollama 的最终运行方式和最终主机。

3. 优先设置 HTTPS_PROXY，按需设置 NO_PROXY。

4. 彻底重启桌面应用、systemd 服务或 Docker 容器。

5. 执行一次实际的 ollama pull 验证。

6. 按最终 URL、方法、模型资源、认证、响应体和日志顺序排查。

7. 确认没有把代理密码、API Key 或完整请求 URL写进日志。

如果你还要把 Ollama 接入 OpenAI 兼容客户端，先单独验证 Ollama 本地 API，再在客户端中填写 Base URL、模型名和 Key；不要把“代理不通”和“客户端接口字段不兼容”放在同一层排查。

相关页面导读

完成 Ollama 网络验证后，如果下一步是接入 AI 工具，可以继续查看：中转接口的 Base URL、模型和 API Key 核验，了解兼容接口接入前的最小请求检查；需要在编辑器中配置接口时，可参考 Cline 的 OpenAI 兼容接口配置；如果使用工作流平台，可查看 Dify 接入 OpenAI 兼容 API。

常见问题

Ollama 配置代理只设置 HTTPS_PROXY 可以吗？

对于模型下载场景，官方 FAQ 建议使用 HTTPS_PROXY，并提醒不要随意设置 HTTP_PROXY，因为模型拉取使用 HTTPS，额外设置 HTTP_PROXY 可能干扰客户端连接。是否需要 NO_PROXY，要看你是否需要让 localhost 或内网地址绕过代理。

为什么设置了 HTTPS_PROXY，Ollama 还是下载失败？

先检查变量是否传给了最终运行 Ollama 的进程，然后确认桌面应用、systemd 服务或 Docker 容器已经重启。接着核对代理协议、主机、端口和证书链，并用实际的 ollama pull 观察错误正文，而不是只查看当前终端变量。

Docker 里的 Ollama 怎么配置代理？

在创建容器时通过 -e HTTPS_PROXY=代理地址传入变量，必要时同时设置 NO_PROXY。已有容器不会因为宿主机后来修改环境变量而自动更新，通常需要重新创建容器。使用 docker inspect 检查时要先脱敏。

HTTPS 代理使用自签名证书怎么办？

将代理所需的 CA 证书安装为运行 Ollama 的系统或容器信任证书，再重新启动 Ollama。不要通过关闭 TLS 校验来绕过证书错误。

Ollama 的出站代理和反向代理有什么区别？

出站代理解决 Ollama 访问模型仓库时如何发出请求，主要涉及 HTTPS_PROXY；反向代理解决其他客户端如何访问本地 Ollama API，通常涉及 OLLAMA_HOST、Nginx 或其他网关。两者的配置位置、验证方法和安全风险不同。

相关阅读

• 中转接口的 Base URL、模型和 API Key 核验
• Cline 的 OpenAI 兼容接口配置
• Dify 接入 OpenAI 兼容 API

参考资料

1. Ollama 官方 FAQ：代理、Docker、证书与网络暴露
2. Ollama 官方源码：环境变量与代理变量读取