视觉引擎

ModLens 不绑定任何单一视觉服务。视觉来源一共十个：六个内置 provider（配好任意一个就能用），加四家本机 agent CLI 的登录可以复用。

内置 provider

kimi-cli 只在被点名时运行，绝不作为无声的故障转移备选。什么都没配时，默认落到 antigravity-cli。

故障转移

不钉死 provider 时，所有配好的引擎组成一条故障转移链：已配置的 API provider 先试（5-10 秒），然后是 agent CLI（15-45 秒）。第一个可用结果胜出，meta.attempts 记录每次尝试，回退永远不是无声的。

modlens config set provider <name> 表达偏好（链继续兜底）。-p <name> 钉死单个，不回退。

openai 是万能接口，不只是 OpenAI

任何讲 OpenAI chat-completions 协议、支持图片输入的端点都能直接插上：

modlens config set openai.baseUrl https://dashscope.aliyuncs.com/compatible-mode/v1   # qwen-vl
modlens config set openai.apiKey  <key>
modlens config set openai.model   qwen3-vl-plus

apiKey（以及对应的环境变量）也接受英文逗号分隔的列表。鉴权、限流或配额失败时会轮换到下一个密钥。网络、5xx 和解析失败会跳过剩余密钥，并继续走现有的 provider 故障转移。

同样三个键，换成 GLM 开放平台、SiliconFlow、OpenRouter、自建 vLLM/Ollama 或你自己的网关都一样。

复用你机器上已有的东西

还有两处现成的视觉能力，一个新 key 都不用配，每家都在你明确同意后才启用：

• **你正在对话的这个 harness 本身。**在登录了订阅的 Claude Code 里用？claude-cli 开箱即可借它读图。装进哪个 harness，安装流程就会问哪个 harness 的授权。
• 机器上其他的 agent CLI。modlens doctor 会逐个发现，你按家授权，它们与你自己的 key 平级入链，不插队。每次复用都在 meta.warnings 里标明花的是谁的额度，绝不无声扣费：

代理环境设 HTTPS_PROXY 或 modlens config set proxy <url>，API provider 自动走代理。

各 provider 配置步骤

antigravity-cli（默认，免费，无需 key）

需要装好 Antigravity CLI 并完成登录：

curl -fsSL https://antigravity.google/cli/install.sh | bash
agy    # 用户需自己在浏览器完成登录，然后退出

任何免费 Google 账号都行，不需要 Google AI Pro。登录无法自动化，请让用户自己跑一次 agy。

gemini-api（免费 key，最快的免费通道，5-10 秒）

1. 用户到 https://aistudio.google.com 创建一个 key（约三分钟，无需信用卡，免费额度不过期）。
2. 两种方式任选其一保存：

modlens config set gemini-api.apiKey <key>
# 省略值：进入隐藏输入，密钥不进 argv、不进 shell 历史，也不进这段对话
modlens config set gemini-api.apiKey

用户就在自己终端前时，先给隐藏输入这条。大多数人图方便还是会把 key 直接贴进对话，那也没问题：照收照存。隐藏输入是留给在乎的人的。

默认模型 gemini-3.6-flash 在免费档就有视觉能力（约每分钟 10-15 次请求，每天 1500 次）。免费档的数据可能被 Google 用于改进产品，用户要处理敏感图片时请提醒这一点。

openai（任意 OpenAI 兼容的多模态端点）

需要三个值。以 DashScope 的 qwen 为例：

modlens config set openai.baseUrl https://dashscope.aliyuncs.com/compatible-mode/v1
modlens config set openai.apiKey <sk-key>
modlens config set openai.model qwen3.6-27b

baseUrl 必填，用官方 OpenAI 也要写（https://api.openai.com/v1）：这条路线服务任意兼容端点，替用户猜一个，就等于把本该发给别家的密钥连同图片一起送到用户从没指定过的地方。模型必须是多模态的，纯文本模型会失败或产生幻觉。

这条路线默认在服务端不做任何约束，能力弱一些的模型可能只答出契约的一半，运行就会以明确报错失败。真遇到就让网关自己强制执行：

modlens config set openai.structuredOutput true

契约会以 response_format: json_schema 的严格形式发出去，schema 由 modlens 校验用的那份推导而来。默认关闭，因为不支持结构化输出的网关会对这个字段返回 400，端点拒绝就关回去。关掉思考（见下）会让结构错误更容易出现，所以这两项常常一起用。

anthropic（Claude API key）

modlens config set anthropic.apiKey <sk-ant-key>

默认模型是 Claude Haiku（claude-haiku-4-5-20251001）。schema 通过强制工具调用来约束。

**ANTHROPIC_BASE_URL 陷阱已经拆掉了。**modlens 过去把这个变量按字段绑到 anthropic.baseUrl，于是一个为了把 Claude Code 路由到纯文本网关而设的变量，会让视觉请求也无声地发到那里，哪怕密钥是在配置文件里设的。现在只要文件里出现 anthropic，文件就是这条路线的全部来源，那个变量再也够不着它，确实想换端点就设 anthropic.baseUrl。而在文件对 anthropic 只字未提时，ANTHROPIC_API_KEY 和 ANTHROPIC_BASE_URL 仍然能独立配好这条路线，两半来自同一处。卡在中间的情况（变量设着、文件里有 anthropic 却没有 baseUrl）会直接报错，并给出保留原端点的那条命令。

kimi-cli（复用 Kimi Code 登录，无需密钥）

搭在已有的 kimi 登录上，花的是用户的 Kimi Code 订阅而不是密钥。先从 https://moonshotai.github.io/kimi-code/ 安装，跑一次 kimi 并 /login，然后：

modlens config set provider kimi-cli
modlens config set kimi-cli.model <alias>   # 可选，不设就用 kimi 自己的默认模型

点名它才会启用。和其他 CLI 路线不同，它不会自己加入故障转移链：它花的是订阅，而装了 CLI 不等于同意花它。

模型别名用 kimi 自己的那套，形如 <provider>/<model>，kimi provider list 能看到，而且必须支持图片输入。这条路线没有服务端 schema 约束（该 CLI 没有 --json-schema），契约是以填好的 JSON 模板随提示词发过去的，能力弱的模型可能只答出一半，遇到就用 -p gemini-api 兜底。

有一个实现细节，调试时值得知道：modlens 运行 kimi 时把 skill 发现指向了一个空目录。否则 kimi 可能在共享的 skill 目录里找到 modlens skill，然后通过调用 modlens 来读图，也就是 modlens 自己调自己。

claude-cli（Claude Code 登录态，无需 key）

借用已有的 claude 登录态，花的是用户的 Claude 订阅额度，不产生单独的 API 账单。需要装好并登录 Claude Code（用 claude --version 检查）。运行时只带 --allowedTools Read。只支持本地图片文件，远程 URL 请改用 gemini-api。默认模型别名 haiku。

modlens config set provider claude-cli   # 用户愿意的话把它设为默认

全部配置键见配置手册。参数与默认模型见 CLI 手册。远程 URL 由谁抓取见安全说明。