通用接入
Lumoswitch 可以作为多个 AI SDK、编码助手和 Web 客户端的统一模型入口。每个客户端都需要以下三个值：
| 参数 | 从哪里获取 | 示例 |
|---|---|---|
| Base URL | 配置 API 创建完成页 | https://your-gateway.example.com/v1 |
| Access Key | 创建配置 API 后仅完整显示一次 | your-lumoswitch-access-key |
| 对外模型名称 | 配置 API 的下游输出设置 | your-public-model-name |
下游客户端只能使用 Lumoswitch Access Key。不要填写上游模型厂商的 API Key。
接入前验证
先在终端验证 Base URL、Access Key 和模型名称是否匹配：
export LUMOSWITCH_BASE_URL="https://your-gateway.example.com/v1"
export LUMOSWITCH_API_KEY="your-lumoswitch-access-key"
export LUMOSWITCH_MODEL="your-public-model-name"
curl "$LUMOSWITCH_BASE_URL/models" \
-H "Authorization: Bearer $LUMOSWITCH_API_KEY"返回结果中应包含 $LUMOSWITCH_MODEL。如果这里失败，应先修复配置 API 或 Access Key，再继续配置客户端。
选择客户端
- OpenAI SDK：在 Node.js 应用中调用 Lumoswitch。
- Codex：通过 Responses API 接入 Codex CLI。
- Claude Code（实验性）：通过控制台生成配置接入，需按客户端版本验证。
- Continue：在编辑器中添加 Lumoswitch 模型。
- Aider：在命令行代码助手中使用自定义模型。
- OpenCode：通过 OpenAI-compatible 配置启动。
- OpenWebUI：在 Web 管理界面中添加连接。
通用排查
| 现象 | 检查项 |
|---|---|
| 401 | 是否误用了上游 Key；Lumoswitch Access Key 是否已停用 |
| 模型为空 | /models 是否返回对外模型名称；Key 是否允许该模型 |
| 404 | Base URL 是否包含 /v1；客户端是否重复拼接了 /v1 |
| Key 格式被拒绝 | 在配置 API 中启用 OpenAI Key 格式兼容 |
| 流式输出异常 | 配置 API 是否允许流式输出；代理是否关闭缓冲 |
| 客户端配置未生效 | 完全退出并重新启动客户端，确认读取的是正确配置文件 |