Ollama API 认证

本地 API 完全不校验身份，云端 API 必须带 Key。这一篇讲清三种场景下的鉴权方式，以及几个容易踩的坑。

版本基线 v0.40.12，官方 docs.ollama.com/api/authentication。

一、三种场景的鉴权要求

一句话：本地管本地，云端管云端。本地服务只在你显式使用云端模型时才会去认证。

二、API Key 的用法

生成

到 ollama.com/settings/keys 创建。Key 不会过期，需要作废时在同一页面撤销。

设置

export OLLAMA_API_KEY="your_api_key"

请求头格式

统一用 Bearer：

curl https://ollama.com/api/chat \
  -H "Authorization: Bearer $OLLAMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemma4:31b",
    "messages": [{"role": "user", "content": "Why is the sky blue?"}],
    "stream": false
  }'

⚠️ Anthropic 兼容端点也只认 Bearer。托管环境的 /v1/messages 不接受单独用 x-api-key——这是和 Anthropic 官方 API 的一个关键差异，容易配错。

三、登录方式：ollama signin

不想在代码里管 Key，可以用 CLI 登录：

ollama signin

登录后 Ollama 会替你认证云端请求，可以直接跑云端模型：

ollama run gpt-oss:120b-cloud

通过本地 API 也生效——模型名带 -cloud 后缀即可：

curl http://localhost:11434/api/generate -d '{
  "model": "gpt-oss:120b-cloud",
  "prompt": "Why is the sky blue?"
}'

这条的巧妙之处在于：请求地址是 localhost，不需要鉴权头，但实际推理发生在云端——凭据由本地 Ollama 保管。

四、安全实践

官方明确提到的两条：

1. 不要把 Key 放到浏览器代码里——前端代码任何人可见
2. 不要把 Key 提交到版本控制

具体做法：

## 环境变量（本地开发）
export OLLAMA_API_KEY="..."

## .env 文件（记得加进 .gitignore）
echo "OLLAMA_API_KEY=..." >> .env

五、常见错误对照

动手试

## ① 验证 Key 有效（返回余额即通过）
curl -s https://ollama.com/api/balance \
  -H "Authorization: Bearer $OLLAMA_API_KEY"

## ② 验证本地无需鉴权
curl -s http://localhost:11434/api/version

## ③ 验证登录状态可用云端模型
ollama run gpt-oss:120b-cloud "hi"

三条分别对应「云端 Key」「本地免鉴权」「CLI 登录」三种鉴权路径。