Agent Zero 模型配置指南：从 API 密钥到端点 URL，10 分钟让 AI 代理开工-平芜编程栈

Agent Zero 模型配置指南：从 API 密钥到端点 URL，10 分钟让 AI 代理开工

【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero

第一次装完 Agent Zero，最卡人的往往不是安装，而是模型配置：密钥填在哪、端点 URL 怎么写、本地模型为什么连不上。这篇按"先自检、再选路"的思路带你把 Agent Zero 模型配置一次跑通，云端 API 密钥和本地 Ollama 两条路都覆盖，并附上常见的"发出去没反应"的排查清单。

配置前先过一遍这份检查清单

别急着进设置页，先确认手头东西齐了。依赖没备好，后面每一步都会卡住。

你走哪条路	必须准备好的东西
云端模型	一家提供商的 API 密钥（OpenRouter、OpenAI、Anthropic、Google 等），以及该密钥对应的可用额度
本地模型（以 Ollama 为例）	宿主机上已安装 Ollama、`ollama pull`下载好模型、模型服务在跑

两条路通用的准备：

Web UI 能正常打开（侧边栏能看到齿轮图标的Settings入口）。
如果你用 Docker 部署 Agent Zero，心里要有个概念：容器里的localhost指向容器自己，不是你的宿主机。这个坑后面会专门讲。
顺手记一下主模型和工具模型的分工：主模型负责对话推理，工具模型负责摘要、命名这类杂活，选个小而快的就行。

路径一：接入云端模型（API 密钥 + 端点 + 上下文）

进设置页后选Cloud provider，流程就三步：

选提供商、填密钥。在 API Keys 区域找到对应提供商的输入框，把密钥粘进去保存。密钥只填一次，之后所有用到该提供商的模型都会复用。
选主模型。提供商定好后，模型下拉框里出现的是该家可用的模型列表。注意命名规则跟提供商绑定：同一家模型，在 OpenRouter 上可能带前缀，在原生 OpenAI 上就不带前缀，照抄错家就会报 Invalid model ID。
调两个上下文参数。这里最容易配错，顺序不能反：

Context Length（总上下文窗口）：先设总量，比如 100k。
Context Window Space（聊天历史占比）：再决定其中多少分给对话历史，是一个"占总窗口多少比例"的概念。

一个容易忽略的点：总窗口设得再大，占比给得再高，实际能用的历史长度是两者相乘的结果。总量先定，比例后调，别反过来。

配置完向导会再让你选一个工具模型。建议挑个小快便宜的（小参数量的开源模型就很合适），摘要、命名这类任务用不着大模型，能明显省钱提速。

路径二：跑本地模型（Ollama 为例）

本地模型的好处是数据不出门，代价是配置细节更多。以 Ollama 为例：

宿主机上装好 Ollama 并拉取模型，例如ollama pull qwen3:8b。
用ollama list确认模型确实已下载。
进 Agent Zero 设置，聊天模型的提供商选Ollama。
模型名必须和服务端完全一致——ollama list里显示什么就填什么，大小写、冒号后面的 tag 都不能差。

端点是这条路上最高发的故障点。Agent Zero 在 Docker 里的默认端点是：

http://host.docker.internal:11434

只要 Ollama 跑在宿主机上，这个默认值通常不用动。真正要检查的是 Ollama 的监听地址：如果它只绑在127.0.0.1:11434，容器通过网络网关依然摸不到它，需要让 Ollama 监听0.0.0.0（并把这个端口限制在可信客户端访问）。Ollama 和 Agent Zero 在同一个 Docker 网络时，也可以直接用容器名替代host.docker.internal。

小参数量本地模型还有个隐藏门槛：默认的通信格式对小模型偏复杂，可能出现"模型在描述工具调用而不是真的调用"。仓库自带的agents/tiny-local/就是为此准备的精简 profile，遇到这种情况可以切过去试试。

安全加固：别让配置页裸奔

模型能跑起来之后，回头把门锁好。这部分都在设置页的认证区域：

Web UI 登录账号密码：给 Web 界面设一道用户名/密码，尤其是容器端口映射到公网或办公网络时。
Docker root 密码：如果你开了 SSH 进容器的能力，把 root 密码改掉。
OAuth 授权类服务：像 GitHub Copilot、Codex/ChatGPT、Google Cloud Gemini 这类走账号登录而非 API 密钥的服务，系统会引导你完成一次浏览器授权，按提示走完即可。

一个细节：截图分享配置界面时，先把密钥打码。密钥一旦流出，等于把账单和权限都递了出去。

跑通验证与排障：一条测试消息定生死

配置保存后，回主界面开一个新聊天，发一句"介绍一下你自己"。有正常回复，说明密钥、端点、模型名三件套都对了；卡住或报错，按下面对号入座：

症状	大概率原因	处理
发消息后毫无反应	密钥没填或没保存	回设置页确认 API Keys 区域不为空
Invalid model ID	模型命名与提供商不匹配	核对前缀规则，比如 OpenRouter 带`openai/`前缀、原生 OpenAI 不带
本地模型连不上	端点指向了容器自身	用`host.docker.internal:11434`，别用`localhost`
端口通了仍超时	Ollama 只监听回环地址	让 Ollama 监听`0.0.0.0`