文档 / 聊天应用
聊天应用ChatboxOpenAI CompatibleChat Apps
Chatbox 接入指南
在 Chatbox 中配置 APIMAX 的 OpenAI 兼容 API，添加模型并排查常见连接错误。
概述#
Chatbox 是跨平台 AI 对话客户端，支持自定义 OpenAI 兼容 API。配置 APIMAX 后，可以在桌面端或移动端使用账号下已开放的对话模型，并在本地管理会话历史。
使用前准备#
- 从 Chatbox 官网 下载最新版客户端。
- 登录 APIMAX 控制台，在 API Keys 创建一个 Key。
- 记录要使用的完整模型 ID。
配置步骤#
不同版本的菜单名称可能略有差异，核心字段相同：
- 打开 Chatbox，进入 设置 → 模型提供方。
- 选择 添加自定义提供方 或 OpenAI API 兼容。
- 填写以下配置：
| 配置项 | 值 |
|---|---|
| 提供方名称 | APIMAX |
| API 模式 | OpenAI API 兼容 |
| API Key | 控制台生成的 Key |
| API Host / Base URL | https://api.apimax.ai/v1 |
| API Path（如单独显示） | /chat/completions |
如果当前版本没有独立的 API Path 字段，只填写 Base URL，Chatbox 会自动请求 /chat/completions。
配置模型#
- 点击刷新或获取模型列表。
- 选择 APIMAX 账号下可用的模型。
- 自动获取失败时，手工输入控制台显示的完整模型 ID。
- 保存并将该模型设为当前会话模型。
建议首次使用普通文本对话模型验证。图片理解、联网搜索、工具调用等能力取决于具体模型，不是所有 OpenAI 兼容模型都支持相同功能。
验证连接#
创建新会话并发送：
text
请只回复“连接成功”，不要添加其他内容。收到回复后，到 APIMAX 控制台的用量日志确认模型、Key 和计费记录是否正确。
参数建议#
首次连通性测试建议使用保守配置：
| 参数 | 建议 |
|---|---|
| Temperature | 0.7；推理模型报错时恢复默认 |
| Max Tokens | 1024 或保持自动 |
| Context Length | 不超过模型页标注的上下文上限 |
| Stream | 开启；异常时可暂时关闭排查 |
常见问题#
Connection failed / Network error#
- 检查 Base URL 是否为
https://api.apimax.ai/v1。 - 检查系统代理、防火墙和 DNS。
- 如果 Host 已经包含
/v1，API Path 不要再次写成/v1/chat/completions，否则会形成重复路径。
401 Unauthorized#
- 确认 API Key 没有多余空格。
- 检查 Key 是否启用、是否已被删除。
模型列表为空#
- 手工输入 APIMAX 模型页显示的模型 ID。
- 确认 Key 对该模型有访问权限。
- 更新 Chatbox，旧版本可能无法正确解析模型列表。
400 参数错误#
- 关闭自定义 Temperature、Top P、最大输出等高级参数后重试。
- 检查当前模型是否支持图片、文件或工具调用。
- 新建一个纯文本会话，排除旧会话上下文中的不兼容内容。
余额不足或无可用渠道#
- 在控制台检查余额和用量。
- 确认模型仍在可用列表中。
- 切换同类模型再次验证。
主备入口切换#
正常情况下始终使用主入口 https://api.apimax.ai/v1。只有确认主入口存在网络故障时，才临时改为控制台公布的备用 API 地址，并保留 /v1 后缀。不要在同一会话中频繁切换入口，以免排查日志时混淆。
安全建议#
- 为 Chatbox 单独创建 Key，并定期轮换。
- 开启系统锁屏和磁盘加密，避免本地客户端配置泄露。
- 导出会话或配置前，检查文件中是否包含 API Key 或敏感对话内容。