企业官网建设流程全解析

Agent Zero 模型接入全路径：云端到本地 5 分钟跑通

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

刚装好 Agent Zero，浏览器一打开，发消息却卡在"模型未配置"；想配吧，设置页里一堆选项卡，API 密钥该填哪儿、本地 Ollama 端点地址写什么，全得靠猜。这就是 Agent Zero 模型配置最容易劝退人的地方。其实它就是把"选模型源、放密钥、填端点"三件事做对而已。看完这篇，你能在云端 API 和本地 Ollama 两条路上任选其一，5 分钟内让 Agent 真正开始干活。

配置全貌：三个决策点先理清

先建立地图感，细节后面再讲。整个配置过程只有三个关键决策：

• 选哪个模型源：云端 API（OpenRouter、OpenAI、Anthropic 等）、AI 账号（Copilot、Gemini 等 OAuth 登录）、还是本地模型（Ollama、LM Studio、vLLM 等）。
• 密钥放哪：API Key 统一在设置页的密钥区管理，别散落在各个输入框里。
• 端点怎么填：云端基本不用管；本地模型需要填你机器的实际地址，Docker 部署时有专门的写法。

配置入口有两个：一是首次打开 Web UI 时的引导向导（发一条消息就会弹出来），二是侧边栏齿轮图标进入的 Settings 页面，其中Settings → Agent → Models可以设置全局默认模型。

场景 A：接云端 API（最省事的路径）

准备：手里有一个云服务商的 API Key。没有账号的话，OpenRouter 一个 Key 能路由多家模型，是新手首选。

操作：

1. 打开 Web UI，随便发一条消息，弹出模型选择门后点Cloud provider，或直接进设置页选Chat Model选项卡。
2. 在 Provider 下拉里选你的服务商（如 OpenRouter、OpenAI、Anthropic、Google）。
3. 在 API Key 输入框粘贴密钥，模型下拉里选主模型（负责对话和推理，选强的）。
4. 接着点Choose utility model配一个工具模型——它是干摘要、命名、记忆这类内部杂活的小模型，选个快而便宜的就行。
5. 点Finish setup或Save保存。

确认：回到聊天窗口发一句"用三句话介绍一下你自己"，能流式回话就说明云端链路通了。

[!TIP] 工具模型别偷懒直接选跟主模型一样的，内部任务调用频繁，用大模型既慢又费钱；同一供应商家选个 Mini / Flash 级别的小模型最合适。

场景 B：跑本地 Ollama（数据不出门）

准备：宿主机上已装好 Ollama 并拉了模型，终端跑ollama list能看到模型名（如llama3.2、qwen2.5:7b），且 Ollama 服务正在运行。

操作：

1. 在模型向导里选Local model，Provider 里选Ollama。
2. 模型名输入与ollama list输出完全一致的名字，一个字母都不能差。
3. 端点地址按部署方式二选一：Agent Zero 跑在 Docker 里就填http://host.docker.internal:11434，本机直接运行就填http://localhost:11434。
4. 同样给工具模型指一个小一点的本地模型，或先指回同一个模型跑通再说。
5. Save保存。

确认：发一条测试消息，10 秒内开始出字就算成功；如果一直转圈，先回宿主机看 Ollama 日志里有没有收到请求。

[!WARNING] 本地小模型容易出现"光说不练"——用文字描述工具调用而不是真的执行。这种情况切到内置的Tiny Local代理档案（Agent Profile），它会收紧小模型的工具调用格式，详见 docs/guides/local-model-tool-use.md。

场景 C：混合与企业内网（密钥集中管）

云端做主力、本地兜底，或者内网只能访问自建推理服务，思路都一样：每个 Provider 的 Key 集中放到设置页的API Keys区域，各给各的，别混着填。

这里同一区域还管理 Web UI 的登录账号和容器 SSH 密码，改完记得 Save。内网自建推理服务（vLLM、llama.cpp 等）走和 Ollama 一样的Local model入口，端点换成你自建服务的地址即可。

确认：ollama list之外的验证手段——让 Agent 做一个需要工具调用的小任务（比如列个目录），观察它是否正常发起工具请求。

高频踩坑速查

• 401 / 认证失败→ Key 复制时带了首尾空格或换行，或 Key 属于另一个服务商 → 清空输入框重新粘贴，保存后重发测试消息。
• 本地模型一直转圈无响应→ 端点地址写错，Docker 容器里localhost指的是容器自己 → 改成host.docker.internal:11434。
• 模型名对了却报找不到模型→ 名字与ollama list输出不一致（少了 tag 或多了前缀）→ 原样照抄列表里的名字。
• 回复是"描述工具"而不是执行工具→ 本地小模型驾驭不了默认的完整协议 → 切换 Tiny Local 档案或按官方文档处理。
• 配完没生效→ 只改了聊天内选项没设全局默认 → 去Settings → Agent → Models确认全局预设。

下一步

1. 建模型预设：把"强主模型 + 快工具模型"存成命名预设，聊天时一键切换。
2. 接外部 API：把第三方服务的调用代码丢进聊天，Agent 学会后把 Key 存进 Secrets 即可复用。
3. 上工具链：连 A0 CLI 让 Agent 操作宿主机真实文件，或配定时任务做周期活。

模型通了，剩下的就是喂它活干——从一条具体的任务开始。

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