OpenClaw 接入视觉模型 Gemini Vision 与 GPT-4V 配置指南
我是 Quentin，OpenClaw 作者，OpenClaw 拼车的维护者。
OpenClaw 默认装好之后只跑文本模型够用了，但只要你做过这几类任务，就会想要视觉能力：
- 让 agent 看 UI 截图、改前端代码
- 把 PDF 论文 / 合同 直接喂进去做摘要
- 调试时贴一张 grafana 截图问”为什么尖刺”
- 设计稿 → 组件代码
这篇讲的是：怎么通过 cp.bizq.net 官方拼车，把 Claude Sonnet 4.6（带 image input）、Gemini 3 Pro Vision、GPT-4V 一起接进 OpenClaw，写成一份统一的 openclaw.json，agent fallback 时也能跨厂商切换。
一行接好包括视觉模型在内的全套配置：
curl -fsSL https://cp.bizq.net/setup.sh | bash -s -- claude-max-20x
三家视觉模型横评
我自己 6 个月里在 OpenClaw 上轮流跑过这几家，先把选型说清楚：
| 模型 | 强项 | 弱项 | 适用场景 |
|---|---|---|---|
| Claude Sonnet 4.6 (vision) | UI 截图改代码极强；理解控件层级 | 长 PDF（>50 页）会丢内容 | 前端改稿 / Bug 截图分析 |
| Gemini 3 Pro / 3.1 Pro Preview | 1M 上下文，整本 PDF 一次喂 | 偶尔幻觉 | 长文档摘要 / 论文阅读 |
| GPT-4V (gpt-5.4 vision) | OCR 能力扎实；图表 → 数据 | 速度偏慢 | 表格识别 / OCR |
实战策略：primary 设为 Claude Sonnet（图文综合最稳），fallback 走 Gemini 3 Pro（长文档兜底），再 fallback 到 GPT-4V（OCR 兜底）。下面给完整配置。
前置准备
1. OpenClaw 最低版本
视觉输入需要 OpenClaw ≥ 0.9.x。先确认：
openclaw --version
openclaw upgrade # 不够新就升级2. 拿拼车 token
OpenClaw 拼车微信群拿一个 token。同一个 token 同时覆盖文本和视觉模型——不需要为视觉单独再开一个。规格按团队规模定制，微信咨询。
3. 备份现有配置
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak.$(date +%s)视觉相关 provider 配置和文本不冲突，但 JSON 编辑出错会让网关起不来，备份是底线。
一键接入
最快路径：
curl -fsSL https://cp.bizq.net/setup.sh | bash -s -- claude-max-20xsetup.sh 默认就把视觉模型加进 models.providers，不用额外参数。跑完之后用一张图测试：
openclaw run --model sonnet --image ./screenshot.png "解释这张图里发生了什么"返回正常文字描述，说明视觉链路通了。
如果你想手动配置或想理解 setup.sh 写出来的内容，继续往下看。
手动配置
视觉模型与文本模型在 OpenClaw 里共用 provider，只是 models[].input 字段要包含 "image"。下面给最小可用配置。
1. models.providers —— 加上 image input
{
"models": {
"providers": {
"carpool-claude": {
"baseUrl": "https://cp.bizq.net/",
"apiKey": "你的令牌",
"api": "anthropic-messages",
"models": [
{
"id": "claude-sonnet-4-6",
"name": "Claude Sonnet 4.6 Vision",
"input": ["text", "image"],
"contextWindow": 200000,
"maxTokens": 8192
},
{
"id": "claude-opus-4-6",
"name": "Claude Opus 4.6 Vision",
"input": ["text", "image"],
"contextWindow": 200000,
"maxTokens": 8192
}
]
},
"carpool-gemini": {
"baseUrl": "https://cp.bizq.net/v1beta",
"apiKey": "你的令牌",
"api": "google-generative-ai",
"models": [
{
"id": "gemini-3.1-pro-preview",
"name": "Gemini 3.1 Pro Vision",
"input": ["text", "image", "pdf"],
"contextWindow": 1000000,
"maxTokens": 8192
},
{
"id": "gemini-3-pro-preview",
"name": "Gemini 3 Pro Vision",
"input": ["text", "image", "pdf"],
"contextWindow": 1000000,
"maxTokens": 8192
}
]
},
"carpool-openai": {
"baseUrl": "https://cp.bizq.net/v1",
"apiKey": "你的令牌",
"api": "openai-responses",
"models": [
{
"id": "gpt-5.4",
"name": "GPT-5.4 Vision",
"input": ["text", "image"],
"contextWindow": 128000,
"maxTokens": 16384
}
]
}
}
}
}要点：
input: ["text", "image"]是 OpenClaw 用来路由多模态请求的关键。漏了就走纯文本，图片会被丢掉- Gemini 多一个
"pdf"，原生支持 PDF 上传不需要 OCR 预处理 - 三家共用一个
apiKey，token 管理简单
2. agents.defaults —— 多模态 fallback
{
"agents": {
"defaults": {
"maxConcurrent": 4,
"model": {
"primary": "carpool-claude/claude-sonnet-4-6",
"fallbacks": [
"carpool-gemini/gemini-3.1-pro-preview",
"carpool-openai/gpt-5.4",
"carpool-claude/claude-opus-4-6"
]
},
"models": {
"carpool-claude/claude-sonnet-4-6": { "alias": "vision" },
"carpool-claude/claude-opus-4-6": { "alias": "vision-opus" },
"carpool-gemini/gemini-3.1-pro-preview": { "alias": "vision-long" },
"carpool-openai/gpt-5.4": { "alias": "vision-ocr" }
}
}
}
}3. 重启网关
openclaw gateway restart视觉调用三种姿势
姿势一：本地文件直传
openclaw run --model vision --image ./bug.png "为什么这个按钮在 mobile 上对不齐？"OpenClaw 会自动 base64 编码上传。单张图建议 < 5MB，太大 Claude 那头会拒绝。
姿势二：URL 直读
openclaw run --model vision --image-url https://cp.bizq.net/static/test.png "描述这张图"适合截图已经 host 在某个 CDN 上的场景。注意 URL 必须公开可访问。
姿势三：PDF 直读（仅 Gemini）
openclaw run --model vision-long --pdf ./paper.pdf "总结这篇论文的三个主要贡献"Gemini 3 Pro 原生吃 PDF，不需要先用 pdftoppm 转图。一篇 100 页 RFC 一次扔进去刚好。
姿势四：编程接口
OpenClaw SDK Python 用法：
from openclaw import Client
client = Client()
result = client.run(
model="vision",
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "这个表格的总和是多少？"},
{"type": "image", "source": {"type": "path", "path": "./table.png"}},
],
}
],
)
print(result.text)常用工作流
1. UI 截图 → React 组件
openclaw run --model vision --image ./design.png \
"把这张设计稿写成 React + Tailwind 组件，注意按钮的 hover 状态。"2. 调试报错截图
openclaw run --model vision --image ./terminal-error.png \
"看截图里的报错栈，告诉我可能是哪几行代码的问题。"3. PDF 合同摘要
openclaw run --model vision-long --pdf ./contract.pdf \
"提取这份合同里的所有金额条款，包括违约金、付款节奏、罚则。"4. 表格 OCR
GPT-4V 在表格 → 结构化数据上比 Claude 略好：
openclaw run --model vision-ocr --image ./table.png \
"把这张表识别成 markdown 表格输出。"验证
视觉链路有三层要分别测：
# 1. provider 通了吗
openclaw run --model vision "你好"
# 2. 图片输入识别吗
openclaw run --model vision --image ./test.png "描述这张图"
# 3. fallback 工作吗（手动构造一个超长 prompt 触发）
openclaw run --model vision --image ./big.png "$(yes 'long context' | head -50000)"第三步应该看到日志里 fallback 到 Gemini 3 Pro。
常见问题
image input not supported by this model
input 字段没有 "image"。回去检查 providers.<name>.models[].input。
image too large
Claude 单张图 5MB 上限，Gemini 20MB。压一下：
ffmpeg -i big.png -vf "scale=1280:-1" small.pngpdf input only supported on gemini
Claude 和 GPT 系列目前不支持原生 PDF。要么转图：
pdftoppm -r 150 paper.pdf page -png要么直接换 --model vision-long。
Token 消耗特别高
视觉 token 是文本的 5-20 倍。对策：
- 降分辨率。1280 宽足够大部分 UI 任务
- 裁剪相关区域。整页截图改成只裁报错那一块
- 批量任务用 Haiku。Haiku 4.5 也支持图，便宜很多
我自己的视觉工作流
OpenClaw + 拼车 + 视觉跑了半年下来，我这套流程：
- 截图统一放
~/Pictures/cc-shots/目录，命名YYYYMMDD-HHMM-keyword.png - CLAUDE.md 里写好「所有 UI 任务前先要求贴截图」
- 设计稿用
vision（Claude Sonnet）；论文用vision-long（Gemini）；表格用vision-ocr（GPT-4V） - token 紧张时切 Haiku 4.5 + 视觉，便宜 10 倍
- 异常状况先 清理本地 Claude Code 缓存，再重跑 setup.sh
立即开始
一行命令把视觉、文本、fallback 全部配好：
curl -fsSL https://cp.bizq.net/setup.sh | bash -s -- claude-max-20x具体团队规模与 token 档位微信咨询。
相关文章
- OpenClaw 接入 cp.bizq.net 官方拼车配置指南 — 文本模型基础接入
- Claude Code 拼车配置完整教程 — 直接用 Claude Code CLI
- Claude Code 5 分钟快速开通 — 最短路径
- Claude Code 缓存清理脚本 — 视觉模型异常排错的第一步