Agent Zero 模型配置指南从 API 密钥到端点 URL10 分钟让 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还有一个真实场景值得记着本地模型偶尔会嘴上答应、手上不动——回复里描述它将要执行的操作却不产生真正的工具调用。这通常不是配置错了而是模型能力与默认协议不匹配换 tiny-local profile 或换稍大的模型一般就解决。进阶入口接下来往哪走配置跑通只是起点几个值得知道的去处首次运行向导与模型接入说明docs/guides/onboarding.md安装与本地模型Ollama / oMLX / llama.cpp / vLLM完整章节docs/setup/installation.md预设管理把快而省本地隐私满血输出存成可切换的 Model Preset见 docs/guides/model-presets.md常见问答与故障排查docs/guides/troubleshooting.md模型提供商清单源码conf/model_providers.yaml各角色 Agent profile含给小模型用的 tiny-localagents/把主模型、工具模型、端点和安全四项都落实你的 Agent Zero 就算正式上工了。剩下的是不断试模型、调窗口找到最合你节奏的组合。【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考