适用于提供“OpenAI Compatible”“OpenAI API”或自定义 OpenAI Base URL 配置项的客户端。具体客户端字段名称会有差异，配置主线保持一致。

​
准备工作

  1. 在 AIMax 平台 创建文本 API Key。
  2. 在平台确认该 Key 当前可见的完整模型名称。
  3. 确认目标客户端支持自定义 Base URL。
  4. 优先使用目标产品的独立集成页；没有独立页面时再使用本页通用配置。

​
填写配置

如果客户端明确说明会自行追加 /v1，API Host 才填写 https://api.aimaxa.cn。不要同时填写 /v1 并让客户端再次追加，否则会形成错误的 /v1/v1/... 路径。

​
选择协议

协议字段和服务端调用示例请看 文本模型总入口，不要把 API 手册中的 curl 命令当作客户端配置步骤。

​
启动验证

  1. 保存配置并完全重启客户端。
  2. 新建一个空白会话。
  3. 发送 只回复 OK，不要调用任何工具。。
  4. 收到回复后，再验证流式输出、文件、工具、联网和多轮对话。

​
常见问题

​
模型列表为空

  1. 检查 Base URL 是否重复包含 /v1。
  2. 检查 API Key 状态和所属分组。
  3. 客户端不支持自动发现时，手工填写平台展示的完整模型名称。

​
返回 401 或 403

  1. 检查 API Key 是否完整，且没有前后空格或换行。
  2. 确认客户端选择的是 OpenAI 兼容 Provider。
  3. 完全重启客户端，避免旧配置或旧账号 Token 继续生效。

​
能回复但工具无法执行

普通文本成功不等于 Agent 工具链已经验证。文件访问、Shell、MCP、联网和客户端本地命令执行需要按具体产品和模型分别验证。