Ollama 登录与鉴权：API 密钥、云模型和本地调用设置

小土豆 技术创作者 2026-11-02 100 阅读

Ollama 登录与鉴权分为两条路径：ollama signin 适合在终端使用云模型，API 密钥适合程序直接访问 ollama.com；本地 http://localhost:11434 默认不需要身份验证。

截至 2026 年 10 月 21 日抓取的 Ollama 官方鉴权文档，已经分别说明终端登录、API 密钥、本地服务和云端 API 的边界。现在最容易配错的地方不是命令本身，而是把本地调用、终端云模型和程序直连云端混为一谈：前者不需要密钥，中间一种依赖终端登录，后一种必须携带 Bearer 令牌。

下文中的路径均依据官方文档与 ollama-js 官方仓库；“适用边界”和“成功标志”是结合官方接口行为作出的操作判断。

先选对鉴权方式

Ollama 的鉴权方式取决于程序访问的是本机服务，还是 ollama.com 上的云端资源。先按实际调用链选择，不需要把所有方式都配置一遍。

使用场景 访问地址 鉴权方式 是否需要 API 密钥
本机运行模型 http://localhost:11434 默认无需鉴权 否
在终端运行云模型 由 Ollama 客户端访问 ollama.com 执行 ollama signin 不手动填写
程序直接调用云端 API https://ollama.com/api 或 https://ollama.com/v1 Authorization: Bearer 是
下载私有模型或发布模型 通过 Ollama 账户操作 登录 ollama.com 视具体操作而定

这里最容易混淆的是 ollama signin 和 OLLAMA_API_KEY：前者让本机安装的 Ollama 客户端获得访问云端资源的账户身份；后者是程序直接请求云端 API 时使用的凭证。终端已经登录，并不等于任意 JavaScript 程序都能直接向 https://ollama.com 发起 API 请求。

终端调用云模型：先执行一次登录

前置条件

  1. 在本机安装可运行的 Ollama。执行 ollama --version；能够显示版本号后继续。
  2. 准备一个可以登录的 Ollama 账户。打开 Ollama 官网，进入登录流程并确认能够进入账户页面。
  3. 终端能够打开浏览器或显示登录链接。执行登录命令后若没有立即打开页面，按终端给出的链接继续。

登录命令来自官方 ollama-js 仓库的 “Cloud Models” 章节：

ollama signin

命令执行后，Ollama 会启动对 ollama.com 的身份验证。官方鉴权文档说明：登录完成后，本地安装的 Ollama 会自动为需要云端访问的请求处理身份验证。

接着可以拉取一个明确带有云端标记的模型：

ollama pull gpt-oss:120b-cloud

随后按普通模型运行：

ollama run gpt-oss:120b-cloud

这条路线适合人在终端里试用云模型，也适合继续使用 ollama run 一类命令。此时不必手工创建或粘贴 API 密钥。

程序直连云端：把密钥填进环境变量

如果代码直接请求 https://ollama.com/api 或 https://ollama.com/v1，需要单独创建 API 密钥。

前置条件

  1. 登录 Ollama 官网，进入账户的 API keys 设置页面，创建密钥。
  2. 在启动 Node.js 程序的同一个 shell 中设置变量。先复制下面这条官方命令，再把 your_api_key 替换成刚创建的密钥：
export OLLAMA_API_KEY=your_api_key
  1. 让 Node.js 进程读取环境变量。在 Linux 或 macOS 中可先检查变量是否存在，避免把密钥直接打印到终端或写进日志：
test -n "$OLLAMA_API_KEY" && echo "OLLAMA_API_KEY is set"

官方文档明确说明：API 密钥目前不会过期，但可以随时在 API keys 设置中撤销。因此，它虽然没有到期时间，仍应按长期凭证管理。

设置完成后，请求头必须使用下面这种形式：

Authorization: Bearer <OLLAMA_API_KEY>

Bearer 是 HTTP 鉴权方案名称，后面的密钥才是实际凭证。只发送 x-api-key 不受 Ollama 的 Anthropic 兼容端点支持；即使请求能连接到服务器，鉴权方式仍不符合官方接口要求。

JavaScript 项目：密钥放在请求头里

安装官方 JavaScript 客户端：

npm i ollama

官方 ollama-js 示例中的完整调用方式如下。代码中的 host 指向云端地址，Authorization 从环境变量读取密钥；不要把真实密钥直接写进 headers。

import { Ollama } from 'ollama'

const ollama = new Ollama({
  host: 'https://ollama.com',
  headers: { Authorization: 'Bearer ' + process.env.OLLAMA_API_KEY },
})
const response = await ollama.chat({
  model: 'gpt-oss:120b',
  messages: [{ role: 'user', content: 'Explain quantum computing' }],
  stream: true,
})
for await (const part of response) {
  process.stdout.write(part.message.content)
}

这里有一个容易漏掉的操作顺序：export OLLAMA_API_KEY=... 只对当前 shell 及其启动的子进程生效。若先安装依赖、随后才打开新的终端，变量可能并不存在于当前进程。可以先运行上面的 test 命令，再启动 Node.js 程序。

另一种写法是让客户端自动读取环境变量：

import { Ollama } from 'ollama'

const ollama = new Ollama()
const response = await ollama.chat({
  model: 'gpt-oss:120b',
  messages: [{ role: 'user', content: 'Explain quantum computing' }],
  stream: true,
})
for await (const part of response) {
  process.stdout.write(part.message.content)
}

官方仓库把这种无参数客户端放在“本地运行”示例中，而前述显式 host 与请求头示例用于云端 API。根据官方文档，若客户端自动读取的环境变量没有传入当前进程，就会缺少云端请求所需的凭证；因此直连云端时，优先采用显式传入请求头的版本，更容易确认密钥是否真正被读取。

常见卡点：密钥有了仍然请求失败

把 API 密钥发到了错误的地址

本地服务 http://localhost:11434 默认不要求身份验证。把 Authorization 请求头发给本地服务，并不会让它自动变成云端鉴权。直接调用云端 API 时，请求地址必须使用：

https://ollama.com/api

或：

https://ollama.com/v1

对应接口选择很重要：/api 使用 Ollama REST API，/v1 提供兼容接口。官方仓库的 JavaScript 示例使用 /api 路径对应的客户端调用方式。

只填写了 x-api-key

官方鉴权文档明确指出，Ollama 的 Anthropic 兼容 /v1/messages 端点也不支持仅使用 x-api-key。处理方法不是增加一个重复请求头，而是改成：

Authorization: Bearer <OLLAMA_API_KEY>

同时确认密钥与请求发往同一个 Ollama 账户。API 密钥属于账户级凭证，拿另一个账户创建的密钥访问当前账户的资源，不会因为请求头格式正确就自动获得权限。

密钥写进了代码或浏览器端

官方文档要求将密钥保存在浏览器代码和源代码控制之外。Node.js 服务端可以读取 process.env.OLLAMA_API_KEY，但不要把密钥随前端代码打包，也不要提交到 Git 仓库。

若密钥已经进入公开日志或仓库，应立即回到 API keys 设置撤销该密钥，再创建新密钥。单纯删除文件中的那一行并不能让已经暴露的凭证恢复安全。

登录后程序仍然不能直连

ollama signin 处理的是 Ollama 客户端发起云端请求时的身份验证。程序直接请求 https://ollama.com 时，仍应配置 API 密钥。可以按这个顺序排查：

ollama --version
ollama signin
test -n "$OLLAMA_API_KEY" && echo "OLLAMA_API_KEY is set"

然后确认代码使用的是：

Authorization: Bearer <OLLAMA_API_KEY>

这条检查链把“客户端存在”“账户已登录”“环境变量已传入”“请求头格式正确”拆开，避免一次改动多个位置后无法判断问题来自哪里。

怎么确认鉴权已经成功

终端登录路线跑通后，执行：

ollama pull gpt-oss:120b-cloud
ollama run gpt-oss:120b-cloud

官方示例中的云模型名称带有 -cloud 后缀；拉取和运行都成功后，终端能够进入交互或返回模型回答，即可确认终端登录链路有效。

程序直连云端时，成功标志不是页面出现某个固定文案，而是请求收到了模型响应对象。官方示例通过 part.message.content 输出内容；启用流式响应后，应持续收到包含 message.content 的响应分片。如果程序没有任何输出，先确认 OLLAMA_API_KEY 已传入启动 Node.js 的那个进程，再检查请求头和主机地址。

本地调用则不需要任何登录步骤。只要 http://localhost:11434 上的服务可访问，调用成功并不代表云端鉴权也已配置好；这是两条彼此独立的链路。

官方入口与继续排查

参考来源

# AI# 知识

评论区

0 条评论

登录后可评论。

小土豆 100 阅读