使用 AIMax 配置 OpenCode

OpenCode 是终端开发工具，支持在 opencode.json 中配置自定义 Provider。AIMax 可以分别通过 OpenAI Chat Completions 和 OpenAI Responses 接口接入，模型 ID 由当前 API Key 的可见模型列表决定。

本文不绑定 OpenCode 或模型版本。OpenCode 的文件编辑、Shell、MCP、子 Agent 和其他工具能力需要在目标模型与协议上分别验证。

安装与准备

按 OpenCode 官方安装说明安装 opencode，然后获取 AIMax API Key：

export AIMAX_API_KEY="YOUR_API_KEY"
export AIMAX_BASE_URL="https://your-domain/v1"

curl --request GET \
  --url "$AIMAX_BASE_URL/models" \
  --header "Authorization: Bearer $AIMAX_API_KEY"

从 data[].id 选择模型，并在后续配置中替换 MODEL_FROM_MODELS。

Chat Completions Provider

如果目标模型通过 /v1/chat/completions 接入，使用 @ai-sdk/openai-compatible：

{
  "$schema": "https://opencode.ai/config.json",
  "model": "aimax-chat/MODEL_FROM_MODELS",
  "provider": {
    "aimax-chat": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "AIMax Chat",
      "options": {
        "baseURL": "https://your-domain/v1",
        "apiKey": "{env:AIMAX_API_KEY}"
      },
      "models": {
        "MODEL_FROM_MODELS": {
          "name": "MODEL_FROM_MODELS"
        },
        "ANOTHER_MODEL_FROM_MODELS": {
          "name": "ANOTHER_MODEL_FROM_MODELS"
        }
      }
    }
  }
}

在项目目录保存为 opencode.json，然后运行：

export AIMAX_API_KEY="YOUR_API_KEY"
opencode

进入后使用 /models 选择已配置模型，也可以通过配置文件的 model 字段指定默认模型。

Responses Provider

如果目标模型通过 /v1/responses 接入，使用 @ai-sdk/openai：

{
  "$schema": "https://opencode.ai/config.json",
  "model": "aimax-responses/MODEL_FROM_MODELS",
  "provider": {
    "aimax-responses": {
      "npm": "@ai-sdk/openai",
      "name": "AIMax Responses",
      "options": {
        "baseURL": "https://your-domain/v1",
        "apiKey": "{env:AIMAX_API_KEY}"
      },
      "models": {
        "MODEL_FROM_MODELS": {
          "name": "MODEL_FROM_MODELS"
        }
      }
    }
  }
}

不要把 Chat Completions 的 @ai-sdk/openai-compatible 和 Responses 的 @ai-sdk/openai 混用。具体模型支持哪个入口，以 AIMax 的实际模型能力和最小请求结果为准。

多模型配置方法

同一个 Provider 可以登记多个模型，或者为不同协议创建多个 Provider：

{
  "provider": {
    "aimax-chat": {
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "https://your-domain/v1",
        "apiKey": "{env:AIMAX_API_KEY}"
      },
      "models": {
        "CLAUDE_MODEL_FROM_MODELS": {},
        "GPT_MODEL_FROM_MODELS": {},
        "GEMINI_MODEL_FROM_MODELS": {},
        "KIMI_MODEL_FROM_MODELS": {},
        "GROK_MODEL_FROM_MODELS": {}
      }
    }
  }
}

模型名称只是示例占位符，不能脱离 /v1/models 结果直接照抄。工具调用、推理参数、上下文长度和多模态能力也需要按模型逐项确认。

最小验证

先运行一个不需要工具的任务：

export AIMAX_API_KEY="YOUR_API_KEY"
opencode --model "aimax-chat/MODEL_FROM_MODELS"

在交互界面输入：

只回复 OK，不要调用任何工具。

基础文本成功后，再验证文件修改、Shell、MCP 和子 Agent。Responses Provider 如果返回适配器错误，先切换到 Chat Provider；反过来也一样。

常见问题

Provider 不出现在 `/models`

确认 opencode.json 位于当前项目目录或 OpenCode 可读取的配置位置。
确认 model 的完整名称为 <provider-id>/<model-id>。
确认 models 中的模型键没有写错。

API Key 没有读取

确认环境变量已经导出，并且配置使用 {env:AIMAX_API_KEY}。也可以运行 opencode auth list 检查凭据状态；不要把完整 Key 提交到项目仓库。

请求路径错误

Chat/Responses Provider 的 options.baseURL 都填写到 /v1 根路径，不要追加 /chat/completions 或 /responses。

集成总览

聊天应用

开发工具

Agent 应用

应用平台

OpenCode

使用 AIMax 配置 OpenCode

安装与准备

Chat Completions Provider

Responses Provider

多模型配置方法

最小验证

常见问题

Provider 不出现在 `/models`

API Key 没有读取

请求路径错误

协议参考

​使用 AIMax 配置 OpenCode

​安装与准备

​Chat Completions Provider

​Responses Provider

​多模型配置方法

​最小验证

​常见问题

​Provider 不出现在 /models

​API Key 没有读取

​请求路径错误

​协议参考

使用 AIMax 配置 OpenCode

安装与准备

Chat Completions Provider

Responses Provider

多模型配置方法

最小验证

常见问题

Provider 不出现在 `/models`

API Key 没有读取

请求路径错误

协议参考