Chatbox 配置 API 与本地模型：新手避坑指南
Chatbox 使用教程里最容易卡住的一步不是安装，而是把模型接进来。
装好客户端只是空壳，真正决定能不能对话的是 API 地址、密钥和模型名这三项。
下面按云端 API 和本地 Ollama 两种场景分别说明填写规则，并给出验证方法和常见报错的处理顺序。
先确认你要接哪类模型
Chatbox 支持 OpenAI 兼容接口和 Ollama 等本地服务。
选哪种取决于你的条件：
- 已有云端 API 密钥，希望开箱即用：选 OpenAI 兼容方式，在 Chatbox 设置里选对应提供商，填入密钥即可。
- 显卡显存够、希望数据不出本机：先在本地跑 Ollama，再让 Chatbox 连
http://localhost:11434。 - 两者都想用：可以在 Chatbox 里添加多个模型来源，对话时手动切换。
关键前提：本地模型必须先启动服务，再打开 Chatbox 配置；
云端 API 要先确认密钥有余额且未被禁用。
云端 API 的填写位置和参数
以 OpenAI 兼容接口为例，进入 Chatbox 设置中的模型提供商页面，添加自定义提供商：
- API 地址（Base URL）：填写服务商文档给出的地址，通常以
/v1结尾，例如https://api.example-provider.com/v1。不要漏掉协议头和路径。 - API Key：粘贴完整密钥，注意前后不要带空格或换行。
- 模型名称：必须和服务商返回的模型列表一致，大小写敏感，不要自己缩写。
填完后保存，回到对话界面新建会话，发一条“你好”测试。
如果收到回复，说明配置生效；
如果报错，先看下一节的排查顺序。
本地 Ollama 的连接方式
先在终端确认 Ollama 服务在运行：
ollama list
curl http://localhost:11434/api/tags第一条能看到已下载的模型列表，第二条返回 JSON 就说明服务正常。
然后在 Chatbox 中添加 Ollama 提供商，地址填 http://localhost:11434，模型名从 ollama list 的输出里原样复制。
如果 Chatbox 和 Ollama 不在同一台机器上，把 localhost 换成 Ollama 所在机器的局域网 IP，并确认防火墙放行了 11434 端口。
连不上时按这个顺序查
- 地址是否多写了路径：Ollama 的地址不要加
/v1，云端兼容接口通常要加/v1，两者规则不同。 - 密钥是否失效：到服务商后台确认密钥状态和余额，必要时重新生成。
- 模型名是否写错：本地模型用
ollama list核对，云端模型用服务商文档或模型列表接口核对。 - 网络是否可达：本地服务用
curl测端口；云端接口在终端用curl -H "Authorization: Bearer 你的密钥" 接口地址/models看是否返回数据。 - 客户端版本是否过旧：如果设置界面找不到对应选项，先升级 Chatbox 再试。
避坑提醒：改完配置后要保存并新建会话，旧会话可能仍引用之前的参数，导致看起来“改了没用”。
验证配置是否真正生效
不要只看设置页显示“已连接”，用一条实际消息验证更可靠：新建会话，发送一句短问题，确认回复内容来自你配置的模型。
再切换一次模型名，看回复风格或响应速度是否变化，能进一步确认没有连到默认模型上。
如果对话正常但回复很慢，先检查本地模型大小和显存占用，再考虑换更小的模型；
如果是云端接口超时，检查网络和密钥额度，不要反复重装客户端。
