Provider 配置与环境变量管理¶
记录 OpenClaw 中模型 Provider 的配置方式、环境变量管理以及常见问题排查。
Provider 体系概览¶
OpenClaw 支持多种模型 Provider，每个 Provider 有独立的认证和配置方式：
| Provider | 认证方式 | 主要模型 |
|---|---|---|
| github-copilot | OAuth | claude-opus-4.6, gpt-5.4, gemini-3.1-pro |
| my-azure | API Key | gpt-5.4, gpt-5.2 |
| minimax-portal | OAuth | MiniMax-M2.5, MiniMax-M2.1 |
| azure-foundry | API Key | 企业级部署模型 |
环境变量配置¶
Azure OpenAI 必需变量¶
export AZURE_OPENAI_API_KEY=your_key_here
export AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com
export AZURE_OPENAI_API_VERSION=2024-02-01
export AZURE_OPENAI_DEPLOYMENT=gpt-5-4
环境变量生效范围¶
问题：只在 ~/.bashrc 配置，exec/systemd 环境读不到
根因：
- 非交互 shell 不会 source ~/.bashrc
- systemd 服务有独立环境
- OpenClaw gateway 以 daemon 方式运行
解决方案：在多个层级配置
1. ~/.bashrc - 交互式 shell
2. ~/.profile 或 ~/.zprofile - 登录 shell
3. systemd service 文件 - daemon 进程
4. OpenClaw 配置文件 - 应用级配置
推荐配置方式¶
在 ~/.openclaw/openclaw.json 中配置 Provider：
{
"providers": {
"my-azure": {
"type": "azure-openai",
"endpoint": "https://your-resource.openai.azure.com",
"apiKey": "${AZURE_OPENAI_API_KEY}",
"apiVersion": "2024-02-01"
}
}
}
Provider 切换¶
查看可用 Provider¶
切换模型¶
动态刷新¶
Provider 模型列表可能动态变化： - 会话刷新后 Provider 元数据重新加载 - 权限/认证状态变化影响可见模型 - 部分模型需要特定权限才可见
Codex 的 Azure 配置¶
问题背景¶
新版 Codex (v0.113.0+) 不再自动识别 AZURE_OPENAI_API_KEY，会错误连接 api.openai.com。
解决方案¶
在 Codex 配置中显式声明 Azure Provider：
同时配置： - Azure endpoint / URL - env 映射 - model 名称
验证连通¶
里程碑：2026-03-13 23:28 Codex 成功连通 Azure OpenAI
常见问题¶
问题 1：模型不可用¶
现象：
根因： - Provider 列表可见不代表实际支持 - 会话状态与模型配置不一致 - 部分模型需要特定部署
解决：
- 使用 /model status 确认当前状态
- 尝试 /reset 重置会话
- 检查 fallback 配置
问题 2：401 认证失败¶
现象：切换模型后 API 返回 401
根因： - Token 过期或无效 - Provider OAuth 需要重新授权 - 环境变量未正确加载
解决：
- 检查 /model status 中的认证信息
- 重启 OpenClaw gateway
- 确认环境变量在运行环境中可见
问题 3：Provider 混淆¶
现象：
- 状态显示 minimax/MiniMax-M2.5
- 实际想用 minimax-portal/MiniMax-M2.5
根因： - 同时存在多个相似名称的 Provider - 模型名称在不同 Provider 中重复
解决：
- 使用完整的 provider/model 格式
- 显式指定目标 Provider
多 Agent 模型配置¶
每个 Agent 可独立配置模型：
{
"agents": {
"list": [
{
"id": "prism-arch",
"workspace": "~/.openclaw/workspace-prism-arch",
"model": "github-copilot/gpt-5.4"
},
{
"id": "prism-pm",
"workspace": "~/.openclaw/workspace",
"model": "github-copilot/claude-opus-4.6"
}
]
}
}
注意：model 字段使用字符串格式，对象格式会导致 fallback 到默认模型。
关键配置经验¶
- 显式优于隐式：不依赖自动推断，显式配置 Provider 和模型
- 环境变量分层：确保在所有运行环境中可见
- 验证后使用：切换模型后端到端验证
- 文档同步：配置变更同步更新到项目文档
参考配置¶
完整 openclaw.json 示例¶
{
"gateway": {
"port": 18791
},
"model": {
"primary": "github-copilot/claude-opus-4.6",
"fallbacks": [
"github-copilot/gpt-5.4",
"my-azure/gpt-5.2"
]
},
"providers": {
"my-azure": {
"type": "azure-openai",
"endpoint": "https://your-resource.openai.azure.com",
"apiVersion": "2024-02-01"
}
}
}