Chatbox 接入指南

概述#

Chatbox 是跨平台 AI 对话客户端，支持自定义 OpenAI 兼容 API。配置 APIMAX 后，可以在桌面端或移动端使用账号下已开放的对话模型，并在本地管理会话历史。

使用前准备#

1. 从 Chatbox 官网 下载最新版客户端。
2. 登录 APIMAX 控制台，在 API Keys 创建一个 Key。
3. 记录要使用的完整模型 ID。

配置步骤#

不同版本的菜单名称可能略有差异，核心字段相同：

1. 打开 Chatbox，进入 设置 → 模型提供方。
2. 选择 添加自定义提供方 或 OpenAI API 兼容。
3. 填写以下配置：

如果当前版本没有独立的 API Path 字段，只填写 Base URL，Chatbox 会自动请求 /chat/completions。

配置模型#

1. 点击刷新或获取模型列表。
2. 选择 APIMAX 账号下可用的模型。
3. 自动获取失败时，手工输入控制台显示的完整模型 ID。
4. 保存并将该模型设为当前会话模型。

建议首次使用普通文本对话模型验证。图片理解、联网搜索、工具调用等能力取决于具体模型，不是所有 OpenAI 兼容模型都支持相同功能。

验证连接#

创建新会话并发送：

请只回复“连接成功”，不要添加其他内容。

收到回复后，到 APIMAX 控制台的用量日志确认模型、Key 和计费记录是否正确。

参数建议#

首次连通性测试建议使用保守配置：

常见问题#

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 或敏感对话内容。