TRAE-AI编程
Ollama Cloud 概览
Ollama Cloud 让你直接从应用或终端调用跑在 Ollama 云端的模型。它最大的好处是不用下载模型、甚至不用装 Ollama——只要一个 API Key，就能用 curl 发起第一次请求。
版本基线 v0.40.12；云端模型清单与定价随时调整，以官方
ollama.com/search?c=cloud与ollama.com/pricing页面为准。
云端适合两类场景：本机显存跑不动的大模型，以及不想在本地维护权重文件、只想要一次 HTTP 调用的轻量集成。代价是请求要出网，涉及隐私数据时请先读本文第四节。
一、API Key：最快的一次云端调用
先去 ollama.com/settings/keys 创建一个 API Key，然后写进环境变量。
## Bash / Zsh：写入当前 shell 会话的环境变量
export OLLAMA_API_KEY="your_api_key"## Windows PowerShell：同样的变量名，写法不同，仅当前会话有效
$env:OLLAMA_API_KEY = "your_api_key"在同一个终端里发一次非流式请求：
## 向云端 Chat 端点发送一条消息
## 关键三点：Base URL 是 https://ollama.com/api（不是 localhost）
## 认证走 Authorization: Bearer
## stream 设为 false，一次拿完整回答
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": "Say hello in one sentence."
}
],
"stream": false
}'
返回体是一个 JSON，回答正文在 message.content 字段里：
{
"model": "gemma4:31b",
"created_at": "2026-10-29T10:00:00Z",
"message": {
"role": "assistant",
"content": "Hello! Nice to meet you."
},
"done": true
}
字段含义逐条对应：model 是实际服务的模型名；created_at 是服务端生成时间；message.role 固定为 assistant；message.content 才是你要取的回答；done 为 true 表示本次输出已结束。
两点安全提醒：
- API Key 不要写进前端代码，浏览器里任何密钥都等于公开；也不要把 Key 提交到 Git 仓库，用环境变量或服务端配置文件。
- 云端请求必须联网，与本地
http://localhost:11434的免认证调用是两套边界，别把两者混用。
这套接口同时兼容 OpenAI 与 Anthropic 客户端，但各客户端只实现原 API 的一个子集，遇到不支持的参数会直接报错。用兼容客户端时不需要安装 Ollama。
二、Ollama App 或 CLI：在本地界面里用云模型
如果更习惯图形界面或命令行，先下载安装 Ollama，然后直接运行：
## 启动交互式入口，按提示完成登录即可使用云端模型
ollama首次运行会走一遍设置引导，登录后云端模型就对当前账号可见。macOS 上还可以打开 Apps，把 Claude 或 ChatGPT 连到 Ollama。
编码代理则用 ollama launch 一条命令拉起，例如 Claude Code：
## 启动 Claude Code，并把模型请求桥接到 Ollama
ollama launch claude
其他集成（Codex CLI、OpenCode 等）同样先用 ollama 打开入口，登录由 Ollama 代为处理，不需要逐个应用单独配置 Key。安装步骤见 1.1 安装 Ollama。
三、模型名的两种写法（最容易踩的坑）
同一个云端模型，在 API 和 CLI 里的名字不一样：
| 使用场景 | 模型名写法 | 示例 |
|---|---|---|
请求 ollama.com 的 API |
用 /api/tags 返回的真实名称 |
gemma4:31b |
| Ollama App 或 CLI 里 | 加 :cloud 后缀 |
gemma4:cloud |
想确认当前账号能用哪些云端模型，直接问接口：
## 列出云端可用模型，取返回里的 name 字段作为 API 的 model 参数
curl https://ollama.com/api/tags \
-H "Authorization: Bearer $OLLAMA_API_KEY"
也可以浏览 ollama.com/search?c=cloud。云端模型不需要下载，这也是它与本地模型最本质的区别——本地模型要 ollama pull 拉权重，云端模型直接调用即可。
四、用量、退役与数据处理
用量与套餐：在 ollama.com/settings/usage 查看当前用量，在 ollama.com/pricing 比较套餐额度。用量统计接口见 13.21 Ollama 云用量统计（Cloud usage） 与 13.22 Ollama 余额查询（Balance）。
模型退役：ollama.com/settings 的用量设置里会列出你近期用过的模型的下线日期，需要在日期前切换模型。注意这条只影响云端：已下载到本地的模型不受影响，仍可继续用。
数据处理：Ollama 会处理你的提示词与模型响应，以便完成这次请求；官方明确表示不会用这些数据训练模型，细节见隐私政策 ollama.com/privacy。如果项目要求数据完全不出本机，可以按官方 FAQ 关闭云功能，只保留本地模型。
五、失败处理
401或提示未授权：OLLAMA_API_KEY没设好，或终端换了会话导致变量丢失；重新export后用echo $OLLAMA_API_KEY确认非空。model not found：API 里写了:cloud后缀，或名称拼错；改用/api/tags返回的真实名称。- CLI 里报模型不存在：反过来，App 与 CLI 场景要用
gemma4:cloud这种带:cloud的写法。 - 请求超时：先确认网络能访问
ollama.com；云端调用不是本机推理，断网必然失败。 - 计费或额度异常：核对是否在套餐额度内，并到用量页确认调用明细。
六、动手试
- 创建 API Key 并
export OLLAMA_API_KEY。 - 用上面的
curl发一条消息，从message.content里读出回答。 - 运行
curl https://ollama.com/api/tags，把你实际看到的云端模型名记下来，替换掉示例里的gemma4:31b。 - 想在自己代码里集成，继续读 1.3 Ollama 用 API 构建应用；想在本机跑模型而不是走云端，回到 1.1 安装 Ollama。
更多建议：