Mods项目中使用OpenRouter API的配置要点解析

在基于命令行的AI工具Mods项目中，正确配置第三方API服务是使用其功能的关键。本文将以OpenRouter API为例，深入讲解配置过程中的注意事项和技术细节。

常见配置错误分析

许多开发者在首次配置OpenRouter API时容易遇到认证失败的问题，这通常源于YAML配置文件的格式规范问题。以下是两个典型错误模式：

1. 环境变量键名拼写错误：将api-key-env误写为apii-key-env，多了一个字母"i"
2. 参数命名不规范：使用下划线格式api_key而非标准的连字符格式api-key

正确配置示例

apis:
  openrouter:
    base-url: https://openrouter.ai/api/v1
    api-key: # 可留空若使用环境变量
    api-key-env: OPENROUTER_API_KEY # 注意连字符格式
    models:
      google/gemini-2.5-pro-proview:
        aliases: ["gemini-pro"]
        max-input-chars: 600000

技术要点说明

1. YAML格式规范：

   • 键名应使用kebab-case(短横线连接)而非snake_case(下划线连接)
   • 缩进必须使用空格而非制表符
   • 字符串值建议使用引号包裹

2. 环境变量优先级：

   • 当同时配置api-key和api-key-env时，环境变量方式具有更高优先级
   • 建议生产环境使用环境变量方式，避免密钥硬编码

3. 模型配置扩展性：

   • aliases字段允许为长模型名设置简写
   • max-input-chars可控制输入长度限制

调试建议

遇到API认证问题时，开发者可以：

1. 使用echo $OPENROUTER_API_KEY确认环境变量已正确设置
2. 检查YAML文件缩进是否准确
3. 尝试在命令行直接调用API验证密钥有效性

通过理解这些配置细节，开发者可以更高效地在Mods项目中集成OpenRouter等第三方AI服务。