lumivia-api

为常见 AI 编程客户端生成网关配置。输入一次 Base URL 和 API Key，工具会探测协议、读取模型目录，再按客户端分别选择模型和思考强度。

支持的客户端

| 客户端 | 写入内容 | 所需协议 | | --- | --- | --- | | Codex | Provider、默认模型、默认思考强度 | OpenAI Responses | | Claude Code | 默认模型、Sonnet / Opus / Haiku 映射、Effort | Anthropic Messages | | Pi | Provider、启用模型、模型能力、Thinking Level Map | 自动选择可用协议 | | OpenCode | Provider、启用模型、模型限制、思考 Variants | OpenAI / Anthropic / Google | | Hermes Agent | Custom Provider、启用模型、默认模型、Reasoning Effort | OpenAI / Anthropic |

Claude Desktop 的账号、扩展和桌面会话配置不属于直接网关模型配置，因此不在本工具中修改。

主要行为

• 掩码输入 API Key，不接受密钥命令行参数
• 探测 OpenAI Chat Completions、OpenAI Responses、Anthropic Messages 和 Google Generative AI
• 过滤图片、音频、Realtime、Embedding 等非 Agent 模型
• Pi、OpenCode 和 Hermes 可分别勾选启用模型，不写入完整模型目录
• Claude Code 可分别指定默认、Sonnet、Opus 和 Haiku 对应模型
• 修改前备份现有文件；含凭证的配置权限设为 0600
• 现有 JSON、JSON5、YAML 或 TOML 无法解析时停止，不覆盖原文件
• 支持 --dry-run 和完整的非交互参数

思考强度

模型能力优先读取网关返回的元数据；元数据缺失时，使用经过核对的主流模型档案。当前覆盖：

• GPT-5.6：off、low、medium、high、xhigh、max
• GPT-5.2 至 GPT-5.5、主流 Codex：low、medium、high、xhigh，支持的型号可关闭
• GPT-5、GPT-5.1、o 系列：按型号提供 minimal / off / low / medium / high
• Claude 4.x / 5：low、medium、high，支持的型号增加 xhigh 和 max
• Gemini 2.5 / 3.x：按型号生成 Thinking Budget 或 Thinking Level
• DeepSeek、Kimi、Qwen、GLM、Grok、MiMo 等推理型号：自动标记，并允许手动覆盖

客户端使用各自格式：Codex 写 model_reasoning_effort，Claude Code 写 effortLevel，Pi 写 reasoning 与 thinkingLevelMap，OpenCode 写模型 variants，Hermes 写 agent.reasoning_effort。

对于未识别但实际支持推理的模型，可以在交互界面手动勾选，或用 --reasoning-models 指定；通用档位为 low、medium、high。

使用

npx lumivia-api

交互流程：

1. 选择一个或多个客户端
2. 输入 Base URL 和 API Key
3. 等待协议与模型探测
4. 为每个目录型客户端勾选启用模型
5. 选择默认模型、角色映射和思考强度
6. 检查摘要并确认写入

非交互示例：

LUMIVIA_API_KEY="your-key" npx lumivia-api \
  --targets codex,claude-code,pi,opencode,hermes \
  --base-url https://api.example.com \
  --models gpt-5.6-terra,gpt-5.6-luna \
  --model gpt-5.6-terra \
  --reasoning-models gpt-5.6-terra,gpt-5.6-luna \
  --thinking high \
  --yes

各客户端也可以单独覆盖：

LUMIVIA_API_KEY="your-key" npx lumivia-api \
  --targets claude-code,pi,opencode \
  --base-url https://api.example.com \
  --claude-model gpt-5.3-codex-spark \
  --claude-sonnet gpt-5.6-terra \
  --claude-opus gpt-5.3-codex-spark \
  --claude-haiku gpt-5.6-luna \
  --claude-thinking xhigh \
  --pi-models gpt-5.6-terra,gpt-5.6-luna \
  --pi-default-model gpt-5.6-terra \
  --pi-reasoning-models gpt-5.6-terra,gpt-5.6-luna \
  --pi-thinking max \
  --opencode-models gpt-5.6-terra \
  --opencode-reasoning-models gpt-5.6-terra \
  --yes

只探测和校验：

LUMIVIA_API_KEY="your-key" npx lumivia-api \
  --targets codex,pi,opencode \
  --base-url https://api.example.com \
  --dry-run \
  --yes

使用 --yes 且没有指定模型列表时，每个目录型客户端只启用自动选中的默认模型。

参数

查看完整参数：

npx lumivia-api --help

通用覆盖参数：

• --models <list>：Pi、OpenCode、Hermes 的启用模型
• --reasoning-models <list>：支持思考的模型；none 表示关闭
• --thinking <level>：默认思考强度
• --model <id>：所有目标默认模型

目标专用参数包括：

• Codex：--codex-model、--codex-thinking
• Claude Code：--claude-model、--claude-sonnet、--claude-opus、--claude-haiku、--claude-thinking
• Pi：--pi-models、--pi-default-model、--pi-reasoning-models、--pi-thinking
• OpenCode：--opencode-model、--opencode-models、--opencode-reasoning-models
• Hermes：--hermes-model、--hermes-models、--hermes-thinking

配置位置

| 客户端 | 配置文件 | | --- | --- | | Codex | ~/.codex/config.toml | | Claude Code | ~/.claude/settings.json | | Pi | ~/.pi/agent/auth.json、models.json、settings.json | | OpenCode | ~/.config/opencode/opencode.json | | Hermes Agent | $HERMES_HOME/config.yaml 或 ~/.hermes/config.yaml |

备份位于对应配置目录下的 backups/lumivia-api/<timestamp>/。

协议边界

本工具根据网关已经提供的协议写配置，不在本地启动协议转换代理。Codex 或 Claude Code 所需的接口不存在时，会在写入前停止并指出缺少的协议。

License

MIT