1. 为什么值得花时间把 OpenCode 配置吃透OpenCode 这个工具最近在开发者圈子里讨论度很高但真正把它用顺手的人其实不多。大部分人卡在同一个地方装是装上了模型也能跑但一到配置环节就懵——模型能力怎么选、模态怎么开、常用选项哪些该动哪些不该动全靠猜。我前后在三个不同环境里折腾过 OpenCode 的配置踩过的坑足够写一本小册子所以这篇就把模型能力、模态支持和常用选项这三块彻底讲清楚。先说清楚 OpenCode 是什么定位。它是一个把 AI 编码能力集成到终端和编辑器里的工具支持多种模型后端可以在命令行里直接对话、生成代码、修改文件也能通过插件挂到 VS Code 或 JetBrains 系 IDE 上。它的核心价值在于把模型能力和开发工作流缝在一起而不是让你在浏览器和编辑器之间来回切换。适合谁看如果你已经在用 AI 辅助写代码但觉得现有工具不够灵活或者你想把不同模型按任务类型分开调度那这篇配置指南就是给你准备的。配置这件事的本质是让工具的行为匹配你的实际工作节奏。OpenCode 的配置项看起来多但真正影响日常体验的就那么几类模型选择与能力映射、模态开关、以及一批控制交互行为的常用选项。下面我按设计思路—核心细节—实操过程—问题排查的顺序展开每一块都会给出具体的配置片段和参数解释你可以直接抄。2. 配置整体设计与思路拆解2.1 配置文件的分层逻辑OpenCode 的配置不是一坨大 JSON 堆在一起而是分层的。理解这个分层后面所有配置项你都能找到该放哪。通常分三层全局配置、项目级配置、会话级覆盖。全局配置放在用户主目录下的配置目录里管的是默认模型、默认模态、通用行为项目级配置放在项目根目录管的是这个项目专用的模型和参数会话级则是你在对话里临时用命令覆盖的设置不落盘。为什么要这么分因为不同项目的需求差异很大。比如你有一个项目专门做前端需要模型对 UI 代码理解好另一个项目做数据处理需要模型擅长写脚本和 SQL。如果只有全局配置你每次切项目都得手动改很容易忘。分层之后全局放你的兜底偏好项目级放这个项目的特殊要求互不干扰。我自己的做法是全局配置只设一个通用模型和一个备用模型模态全部关掉省资源然后在每个项目根目录放一个项目级配置按项目类型开对应的模态、指定专用模型。这样切换项目时行为自动跟着变不用记。2.2 模型能力映射的设计考量OpenCode 本身不训练模型它是个调度层。所以模型能力这块的配置本质是告诉 OpenCode我有哪些模型可用、每个模型擅长什么、什么任务该路由到哪个模型。这里有个关键概念叫能力标签capability tag你可以给每个模型打上标签比如code、reasoning、fast、long-context然后在任务配置里引用标签而不是硬编码模型名。这么设计的好处是解耦。假设你原来用 A 模型做代码生成后来换成 B 模型如果配置里到处写的是 A 的名字你得全局替换但如果写的是code标签只需要改标签到模型的映射关系一处改动全生效。这个思路和很多调度系统的别名机制是一样的。选型上要考虑几个维度上下文窗口大小、是否支持工具调用、是否支持多模态输入、推理速度和成本的平衡。我一般会把模型分成三档快档日常补全、简单问答、主力档代码生成、重构、重档复杂推理、架构设计。快档用轻量模型主力档用中等规模重档才上大模型。这样成本可控响应也快。2.3 模态开关的取舍原则模态modality在 OpenCode 语境里指的是模型能处理的输入输出类型——文本、图像、音频等。多模态模型能同时理解文字和图片比如你截个 UI 图让它生成对应代码或者贴个报错截图让它分析。但多模态不是免费的开启后请求体积变大、延迟变高、部分模型还会额外计费。所以模态配置的核心原则是按需开。默认全关只在确实需要处理图像输入的项目里开。我见过有人图省事全局开了多模态结果每次纯文本请求也走多模态通道白白增加延迟。正确的做法是在项目级配置里按需开启并且指定哪些模型支持多模态避免把图像请求路由到纯文本模型上导致报错。2.4 常用选项的默认值哲学OpenCode 的常用选项有一大堆但我的建议是先全部用默认值跑通再逐个调整。因为很多选项之间存在隐式依赖你一次性改五个出了问题根本不知道是哪个引起的。默认值是作者调过的平衡点对大多数场景够用。真正值得优先调的选项其实就几个自动保存/自动应用改动的开关、上下文携带的历史轮数、工具调用的超时时间、以及输出格式偏好。这几个直接影响你日常用起来顺不顺。其他的等遇到具体问题再动。3. 核心细节解析与实操要点3.1 模型能力配置的字段详解模型能力配置通常写在一个模型列表里每个条目包含几个关键字段。我拿一个典型配置举例说明每个字段的作用{ models: { fast-local: { provider: local, model: small-instruct, capabilities: [fast, chat], contextWindow: 8192, supportsTools: false }, main-code: { provider: cloud-a, model: code-large, capabilities: [code, reasoning], contextWindow: 128000, supportsTools: true }, vision-model: { provider: cloud-b, model: multimodal-v1, capabilities: [code, vision], contextWindow: 32000, supportsTools: true, modalities: [text, image] } } }provider是后端提供方标识model是具体模型名这两个是必填。capabilities是能力标签数组用于任务路由。contextWindow是上下文窗口这个值要填准确填大了会导致请求被后端拒绝填小了浪费能力。supportsTools表示是否支持工具调用函数调用这个很关键——如果你的工作流依赖 OpenCode 去读写文件、执行命令那必须选支持工具调用的模型否则这些功能用不了。modalities只在多模态模型上出现声明它支持哪些输入类型。注意contextWindow不要凭印象填。同一个模型在不同 provider 上的窗口可能不一样以你实际接入的那个 provider 的文档为准。填错这个值是最常见的报错来源之一。3.2 任务路由配置怎么写有了模型列表接下来要配路由规则告诉 OpenCode 什么任务用什么模型。路由配置一般长这样{ routing: { default: main-code, rules: [ { match: { task: completion }, use: fast-local }, { match: { task: refactor }, use: main-code }, { match: { task: architecture }, use: main-code }, { match: { hasImage: true }, use: vision-model } ] } }规则从上往下匹配命中第一条就停。所以顺序很重要把最具体的规则放前面最泛的放后面。比如hasImage这条要放在前面否则带图片的请求可能先被task: completion匹配走路由到不支持图像的模型上。我踩过的一个坑是把default设成了一个不支持工具调用的快模型结果所有需要读写文件的操作全部失败报错信息还不明显排查了半天才发现是路由问题。所以default一定要设成能力最全的那个模型快模型只通过具体规则去命中。3.3 模态配置的开启与限制模态配置分两部分声明模型支持哪些模态以及控制哪些请求允许携带非文本内容。前者在模型定义里上面的modalities字段后者在全局或项目配置里{ modality: { allowImageInput: true, maxImageSizeMB: 5, imageFormats: [png, jpg, webp], fallbackToText: true } }allowImageInput是总开关。maxImageSizeMB限制单张图大小这个必须设否则用户贴个大图直接把请求撑爆。imageFormats白名单只允许常见格式避免奇怪格式导致解析失败。fallbackToText是个很实用的选项当图像请求被路由到不支持图像的模型时是否降级为纯文本处理比如只提取图片里的文字描述而不是直接报错。提示fallbackToText建议开启。实际使用中经常出现当前模型不支持图像但用户贴了图的情况直接报错体验很差降级处理至少能让对话继续。3.4 常用选项逐个说清楚常用选项这块我挑几个真正影响体验的讲。第一个是自动应用改动的开关通常叫autoApply或类似名字。开启后模型生成的代码改动会直接写入文件关闭则只展示 diff等你确认。我的建议是新手阶段关闭养成看 diff 的习惯熟练之后对低风险任务比如格式化、加注释开启高风险任务重构核心逻辑保持关闭。第二个是上下文历史轮数historyRounds。这个值决定每次请求携带多少轮历史对话。设太大请求体积膨胀、成本上升设太小模型记不住前面的上下文回答会断片。一般设 10 到 20 轮比较平衡。如果你的任务经常需要长对话可以配合上下文压缩功能而不是一味加大这个值。第三个是工具调用超时toolTimeoutMs。OpenCode 执行文件操作、命令调用时有超时限制默认值可能偏短遇到大文件操作会超时。我一般设成 30000 毫秒30 秒给足余量。但也不要设太大否则卡住的时候你要等很久。第四个是输出格式偏好outputFormat可选markdown、plain、diff等。日常对话用 markdown代码改动用 diff脚本化调用用 plain。这个按场景切没有固定最优值。4. 实操过程与核心环节实现4.1 从零开始的最小可用配置先给一个能跑起来的最小配置你照着填就能用。假设你只接一个云端模型{ models: { main: { provider: your-provider, model: your-model-name, capabilities: [code, chat], contextWindow: 32000, supportsTools: true } }, routing: { default: main }, options: { autoApply: false, historyRounds: 15, toolTimeoutMs: 30000, outputFormat: markdown } }这个配置没有任何模态、没有复杂路由就是单模型跑通。先确认这个能正常工作再往上加东西。很多人一上来就配一堆模型和规则结果基础链路没通排查起来极其痛苦。4.2 多模型分档配置的完整过程跑通最小配置后开始加模型分档。第一步确定你有哪几个模型可用分别记下它们的 provider、模型名、上下文窗口、是否支持工具调用。这一步建议做个表格模型标识用途上下文窗口工具调用多模态fast-local补全、简单问答8192否否main-code代码生成、重构128000是否vision-model图像理解、UI 转代码32000是是heavy-reason架构设计、复杂推理200000是否第二步把这张表翻译成模型配置。第三步写路由规则按具体到泛化排序。第四步设default为能力最全的模型。第五步逐条测试发一个纯文本请求确认走的是 main-code发一个带图的请求确认走的是 vision-model发一个补全请求确认走的是 fast-local。测试路由是否生效可以看 OpenCode 的日志输出通常会打印实际使用的模型标识。如果日志里显示的模型和你预期不符就是路由规则顺序或匹配条件有问题。4.3 模态功能的实际接入步骤开启图像输入需要几步配合。首先确认你有一个声明了modalities: [text, image]的模型。然后在全局或项目配置里开allowImageInput。接着设好大小限制和格式白名单。最后在路由里加一条hasImage规则指向多模态模型。实际使用时你在对话里贴图OpenCode 会检测到图像内容触发hasImage规则路由到多模态模型。如果此时多模态模型不可用比如网络问题fallbackToText生效降级为文本处理。这里有个细节图像在请求里通常是 base64 编码传输的所以maxImageSizeMB设 5MB 意味着 base64 后大约 6.7MB 的请求体。如果你的 provider 对请求体大小有限制这个值要相应调小。我一般设 3MB够用且安全。4.4 配置验证与生效检查配置写完不代表生效。OpenCode 一般有配置校验命令或者启动时会打印加载的配置摘要。我习惯用两步验证第一步跑一个config validate之类的命令具体命令名看版本确认语法没问题第二步实际发几个不同类型的请求看日志里的模型路由是否符合预期。如果配置改了但行为没变先检查是不是有更高优先级的配置覆盖了。前面说的三层配置项目级会覆盖全局会话级会覆盖项目级。有时候你在全局改了但项目目录里有个旧配置没删行为就一直不对。这个坑我踩过不止一次。5. 常见问题与排查技巧实录5.1 模型路由不生效的排查顺序路由不生效是最常见的问题。排查按这个顺序走先看日志里实际用的模型标识是什么确认是不是路由没命中再检查规则顺序是不是泛化规则排在了具体规则前面然后检查匹配条件字段名对不对不同版本字段名可能有差异最后确认default有没有设没设 default 且规则都没命中时会报错。我遇到过一次特别隐蔽的规则里写的是task: completion但实际请求的 task 值是complete差一个字母永远匹配不上。所以匹配条件的值一定要以实际日志输出为准不要凭记忆写。5.2 上下文窗口报错的典型原因报错信息里出现 context length exceeded 或类似字样通常是三个原因之一contextWindow填大了实际 provider 限制更小historyRounds设太大历史对话累积超限单次输入内容本身太长。排查时先把historyRounds调小试试如果还报错就是contextWindow填错了去 provider 文档核对准确值。注意有些 provider 的上下文窗口是输入输出总和有些只算输入。填配置时要搞清楚是哪种否则按输入窗口填了总和窗口输出一长就超限。5.3 工具调用失败的常见场景工具调用失败一般表现为模型说我要读取文件但实际没读或者报权限错误。原因可能是模型本身不支持工具调用supportsTools设错了也可能是工具超时toolTimeoutMs太短还可能是工作目录权限问题。排查时先确认模型支持工具调用再加大超时时间试试最后检查文件系统权限。我遇到过一次是工作目录设错了OpenCode 在错误的目录里找文件当然找不到。配置里如果有工作目录相关的选项一定要设对。5.4 多模态请求被拒绝的处理贴图后报错 model does not support image input说明请求被路由到了不支持图像的模型。检查hasImage规则是否存在、是否排在前面、指向的模型是否声明了 image 模态。如果都对了还报错可能是 provider 层面不支持那就只能换模型或降级为文本。下面这张表把常见问题和对应处理整理在一起方便速查现象可能原因处理方式路由不生效规则顺序错/字段名错按日志实际值核对具体规则前置上下文超限窗口填错/历史太长核对 provider 文档调小 historyRounds工具调用失败模型不支持/超时/权限检查 supportsTools加大超时查权限图像请求被拒路由错/模型不支持检查 hasImage 规则确认模型模态声明配置改了没生效被上层配置覆盖检查项目级和会话级配置5.5 几个我踩过的坑和独家技巧第一个坑配置里的注释。有些 JSON 配置支持注释JSONC有些不支持。如果你在不支持注释的格式里写了注释整个配置会解析失败但报错信息可能很模糊。我的做法是配置里绝不写注释要记的东西写在单独的笔记里。第二个坑模型名大小写。有些 provider 的模型名区分大小写Code-Large和code-large是两个东西。复制模型名的时候一定要原样复制不要手打。第三个技巧给每个模型配置加一个description字段如果支持的话写清楚这个模型是干嘛的。过几个月你回来看配置光看模型名根本想不起来当初为什么这么配。第四个技巧配置改动前先备份。OpenCode 的配置一般是个单文件改之前复制一份出问题能快速回滚。我现在的习惯是配置目录里保留最近三个版本命名带日期。第五个技巧如果同时用多个 provider注意它们的认证信息管理。不要把密钥硬编码在配置里用环境变量引用。配置里写${PROVIDER_A_KEY}这种形式密钥放环境变量既安全又方便切换。6. 配置维护与长期使用建议配置不是一次性的活用久了肯定要调。我的经验是每换一个项目类型就审视一次配置是否需要调整每接一个新模型就更新一次模型列表和路由每隔一两个月清理一次不再使用的模型配置避免配置膨胀。另外OpenCode 这类工具版本迭代快配置字段偶尔会变。升级版本后先看更新日志里有没有配置相关的变更再决定要不要动现有配置。我一般升级后先跑一遍验证流程确认现有配置在新版本下还能正常工作再考虑用新特性。关于数据安全这块配置里涉及 provider 认证和可能的本地缓存路径。认证信息走环境变量缓存路径如果包含敏感内容注意目录权限。多人共用的机器上配置文件权限设成仅本人可读。最后说一个实际体会配置的价值不在于多复杂而在于稳定可预期。一套简单但你能完全掌控的配置比一套花哨但你不知道哪里会出问题的配置强得多。我现在的配置就三个模型、四条路由规则用了大半年没出过问题因为每一行我都知道为什么这么写。