OpenCode 避坑实战：选型、梯子、PDF 一次讲透

OpenCode 开源、多模型、可高度定制，是很多人手里的「瑞士军刀」。但面对 Zen 与 Go 双轨模型、国内外模型对网络的不同要求，以及「读不了 PDF」这类真实痛点，新手很容易踩坑。本文基于 OpenCode / OpenClaw 官方文档与社区反馈，把模型选型、梯子问题、PDF 实战一次讲清。

一、模型选型：没有万能模型，按需精准匹配

在 OpenCode 里做科研编程，不存在一个放之四海皆准的「最强模型」。核心策略是按任务类型匹配模型能力，并善用 OpenCode Zen 的免费模型压低成本。下面按学术场景给出选型建议。

综合推理与硬核理科：Claude Opus 4 是首选

Claude Opus 4 在代码审查、复杂算法设计、多步指令跟随上表现顶尖，尤其适合核心研究模块的推导与 Review。它是需要高正确性的重活的首选。

数学与代码竞赛级任务：DeepSeek V4 是「理科状元」

DeepSeek V4 系列在数学校验与代码生成上很强，且性价比突出，是高频实验编程的划算选择。日常脚本也可直接用更轻量的 DeepSeek V4 Flash。

超长论文与全库分析：Gemini 2.5 Pro 是「长文本之王」

Gemini 2.5 Pro 拥有百万级 Token 上下文，是通读整篇 PDF、做跨文件依赖分析的首选；结构化输出能力也适合快速提取风险点与性能瓶颈。若涉及图表、公式、音视频的复合文献分析，可关注更新的 Gemini 3 Pro。

中文与本地化科研：Qwen3 系列是「本土化专家」

Qwen3（含 Qwen3-Coder）对中文技术语境、LaTeX 公式、本地部署支持极佳，且有开源权重可走校内 vLLM 离线部署，兼顾理解力与数据安全感。

免费与长文本兜底：Kimi / Nemotron 免费版

Kimi 长文本阅读优秀，适合预算有限的日常辅助；Nemotron 免费版提供百万级上下文、零成本，适合前期文献调研与粗糙草稿。注意其在高精度专业场景中偶有瑕疵，关键结论仍需人工核验。

二、梯子不是「必需品」，而是「可选配件」

用 OpenCode 不一定需要梯子，这完全取决于你连的模型厂商。OpenCode 本身只是开源编程智能体框架，不绑定任何模型，要不要代理由你接的 AI 模型决定。

不需要梯子的场景：

• OpenCode Zen 免费模型：内置经过验证的免费模型集合，无需注册、无需 API Key、无需梯子，装好即用，门槛极低。
• 国产或本地模型：配置智谱 GLM、通义千问 Qwen 等国产模型，或用 Ollama 跑本地开源模型，通常也无需梯子即可稳定连接。

需要梯子的场景：

• 配置并使用 Claude、GPT、Gemini 等海外模型 API 时，因网络限制通常需要代理才能正常连接（OpenCode 配置里也可通过自定义 baseURL 指向代理服务）。

重要提醒：对国内模型，开着梯子反而可能导致网络不稳或响应异常。如果用国产模型遇到问题，请优先尝试关闭梯子再试。

三、Zen 与 Go：双轨并行，各司其职

在 OpenClaw 体系中，OpenCode 提供两个独立但共用一套认证的模型托管目录，构成它的多模型生态：

两者共用同一个 OPENCODE_API_KEY，但运行时按前缀路由到对应后端，互不干扰。在 OpenClaw 里分别用命令接入即可：

openclaw onboard --auth-choice opencode-zen 配置 Zen 目录；openclaw onboard --auth-choice opencode-go 配置 Go 目录。可按任务类型自由切换模型源。

四、实战：OpenCode 读不了 PDF 怎么办

不少科研用户会发现：让 OpenCode 直接读 PDF，常常报「模型不支持 PDF」「functionality not supported」。这并非技术缺陷，而是它作为专业编程智能体的主动取舍——理解设计逻辑、掌握正确应对，比单纯比较工具优劣更重要。

4.1 为什么默认读不了 PDF

OpenCode 本质是面向代码与文本项目的智能体，默认以纯文本（.txt、.py、.json 等）为处理对象，并不内置 PDF 解析。社区里常见的 PDF 报错，根源在于它默认走的是纯文本通道。这种「不原生支持」的设计，恰恰是为了保持工具的轻量、高效与隐私安全——它不预装庞大的解析库，而是把文件处理的选择权交给用户。

4.2 标准化应对流程

面对 PDF 文献，建议建立一套「先转文本、再投喂」的标准化流程，把繁琐操作交给 OpenCode 自己完成：

• 让 OpenCode 写转换脚本：这正是它的强项。直接对它说「帮我写一个 Python 脚本，把当前目录下所有 PDF 转为同名 TXT，保留段落结构」，它会生成基于 PyMuPDF（pymupdf） 或 pdftotext 的脚本并可直接运行，免去逐个手动转换的效率损耗。
• 用 @ 引用把文本加入对话：转换后的 TXT 文件，在 OpenCode 里用 @ 文件名 进行模糊引用，文件内容会自动加入上下文。若需保留表格或公式结构，可要求 AI 转换时加上 Markdown 标记，确保后续分析准确。
• 敏感文献本地化处理：未发表论文、实验数据等，转换全程在本地完成，无需上传任何云端服务，从源头规避数据泄露风险。

4.3 工具组合策略（与第三节的「模型双轨」不同）

这里说的是工具层面的分工，和第三节 Zen/Go 模型目录双轨不是一回事：

• 用支持文档解析的通用 AI 对话工具做「文献预处理」：公开或非敏感资料，直接上传 PDF 做快速阅读、总结与对比，利用它们原生的文档解析能力提升前期调研效率。
• 用 OpenCode 做「代码与数据核心」：把转换后的 TXT 或结构化数据交给它，用于代码复现、数据分析与本地隐私计算。两者分工明确，既避开 OpenCode 在文档解析上的短板，又发挥其在编程与本地化上的专长。

隐私提醒：标注 Free 的免费模型，其使用条款可能允许将交互数据用于训练或评测。处理敏感 PDF 时，即便已本地转换规避了上传风险，用免费模型做分析仍可能留痕。建议敏感内容优先用付费模型或本地部署的开源模型，确保全流程数据安全。

五、实操建议：打造分层科研编程工作流

• 日常脚本编写：优先 DeepSeek V4 Flash 或 Claude Sonnet 系列，成本低且效率够用。
• 核心推导与代码 Review：切到 Claude Opus 4，确保正确性。
• 大部头论文分析：先用通用 AI 工具读 PDF 做综述，再用 Gemini 2.5 Pro 做超长上下文与结构化提取。
• 中文文档与本地部署：选 Qwen3 系列，兼顾理解力与安全性。
• PDF 文献：本地脚本转 TXT → 用 @ 引用投喂 OpenCode，敏感内容走付费/本地模型。
• 网络环境：国内模型优先关梯子，海外模型按需开，避免网络波动影响体验。

写在最后

OpenCode 的强大，不在于给了某个「最强模型」，而在于让你能根据任务、成本、网络环境自由组合模型；它「不读 PDF」也不是缺陷，而是把文件处理的主动权交还给你。掌握这套「按需匹配、双轨并行、网络适配、文本先行」的底层逻辑，让 AI 真正成为科研路上的智能协作者。

注：文中模型定位基于 OpenCode Zen / OpenClaw 官方文档与社区反馈整理；PDF 处理方案为社区验证的通用做法（PyMuPDF / pdftotext）。各模型具体表现会随版本迭代变化，落地前建议以官方当前文档为准。本文由「愚见数字化」整理，关注我们，把 AI 工具真正用起来。