OpenClaw 配置百炼 API 密钥 401 错误排查指南

问题现象

在使用 OpenClaw 连接阿里云百炼（Bailian）模型服务时，即使已经购买了 Coding Plan 并按照官方文档正确配置了 BaseUrl 和专属 API KEY，仍然持续遇到以下错误：

HTTP 401: Incorrect API key provided. For details, see: https://help.aliyun.com/zh/model-studio/error-code#apikey-error

问题根源

经过排查发现，问题出在 OpenClaw 的配置层级覆盖机制上。

OpenClaw 的模型配置遵循以下优先级顺序：

1. Agent 特定配置：openclaw/agents/main/agent/models.json
2. 全局配置：~/.openclaw/config.json
3. 环境变量

当 models.json 文件中存在 bailian 相关的 API 配置时，这些本地配置会优先于全局配置中的 Coding Plan 凭据被使用。

即使用户后来购买了 Coding Plan 并在全局配置中更新了正确的 API KEY，但 models.json 中的旧配置（可能是之前测试时留下的）仍然具有更高优先级，导致系统继续使用错误或过期的凭据进行认证。

解决方案

方法一：清理本地配置（推荐）

删除或清空 agent 特定配置文件中的百炼相关配置：

# 编辑 models.json 文件
nano openclaw/agents/main/agent/models.json

# 删除 bailian 节点下的所有配置，或者直接删除整个 bailian 节点

清理后，OpenClaw 会自动回退到使用全局配置中的 Coding Plan 凭据，认证即可正常工作。

方法二：同步配置

如果确实需要在 models.json 中保留特定配置，确保其中的 API KEY 和 BaseUrl 与 Coding Plan 的凭据完全一致：

{
  "bailian": {
    "apiKey": "your-coding-plan-api-key",
    "baseUrl": "your-coding-plan-base-url"
  }
}

最佳实践建议

1. 统一配置管理

• 使用 Coding Plan：建议只在全局配置 ~/.openclaw/config.json 中设置凭据
• 避免重复配置：不要同时在多处配置相同的模型服务

2. 配置备份

修改配置文件前先进行备份：

cp openclaw/agents/main/agent/models.json models.json.backup

3. 验证配置优先级

当遇到认证问题时，按以下顺序检查配置：

1. 检查 models.json 是否有冲突配置
2. 验证全局配置是否正确
3. 确认网络连接和 API 权限

总结

这个问题本质上是 OpenClaw 灵活配置机制的一个副作用。本地 agent 配置的高优先级设计初衷是为了支持多环境、多模型的复杂场景，但在简单的单环境使用场景下容易造成配置混淆。

通过理解配置的优先级机制，可以快速定位和解决类似的认证问题，避免在错误的方向上浪费排查时间。