说句实话我最早接触 OpenCode AI 编程助手时装完默认配置跑起来感觉就是个稍微聪明点的自动补全。直到某次被一个几百行的跨文件重构任务逼到墙角才开始认真研究它的高级配置改完直接真香。同样是这个工具默认配置和精细配置过的版本用起来完全是两种东西。很多人说某个 AI 编程助手“不好用”往往不是模型不行而是配置没有跟上去。这篇文章不聊基础操作专门聊高级配置——那些不会写在“欢迎页”里、但真正决定效率上限的选项包括配置体系、模型路由、上下文管理、规则注入、性能与安全调优以及我实际踩过的坑。1. 默认配置能用但高级配置才是分水岭1.1 默认配置到底缺了什么OpenCode 装完以后默认配置基本是“开箱即用”的思路一个通用的对话模型、自动补全、基础的编辑器集成。这套配置足够你应付日常的代码生成、解释、改 bug但如果你是个每天要处理大量真实业务的开发者很快就会碰到几个绕不开的瓶颈。第一个瓶颈是模型选择太单一。默认配置通常只指定了一个主力模型但实际开发里写一个 git commit 信息、做一次代码审查、解释一段复杂逻辑、生成一大块脚手架代码这些任务的难度和对延迟的容忍度完全不一样。用同一个模型处理所有事情要么钱花得冤枉要么等得心烦。第二个瓶颈是上下文窗口的浪费。OpenCode 默认会把当前文件、选中的代码、最近的对话历史一起塞给模型。项目小的时候无所谓一旦你在一个几万行代码的仓库里工作默认策略会把大量无关的文件片段也带进去模型反而抓不住重点回答质量肉眼可见地下降。第三个瓶颈是规则缺失。默认配置不懂你的团队规范缩进用几个空格、变量命名风格、禁止直接提交密钥、接口调用的统一封装方式……这些如果不通过配置固化到 OpenCode 的行为里每次生成代码都需要你手动纠正那体验就和“人工调教 AI”没什么区别了。1.2 什么样的人值得投入时间做高级配置如果你只是偶尔用 AI 助手改个脚本那确实不需要折腾高级配置默认的够用。但下面这几类人我强烈建议认真读下去在大中型项目里日常使用 OpenCode 的开发者。仓库一大上下文管理和模型路由的收益立竿见影。对代码质量和安全有要求的团队。规则注入和敏感信息过滤能帮你在源头减少 bad case。用 OpenCode 跑自动化任务的人。自定义命令和 hooks 能把重复操作从几分钟压缩到几秒。对 API 成本敏感的用户。通过模型路由把简单任务分给便宜模型一个月下来省下的费用肉眼可见。高级配置听起来“高级”其实不是让你去改 OpenCode 的源码而是把它的配置能力吃透。后面每个章节我都会给出能直接落地的配置片段和解释你可以按需取用。1.3 高级配置的四大核心方向在深入细节之前先给你一张地图避免一头扎进配置文件里迷路。OpenCode 的高级配置基本围绕四个方向展开这也是我和身边开发者验证之后公认最出效果的维度配置体系与优先级搞清楚全局配置、项目配置、环境变量之间怎么叠加、覆盖这是所有高级操作的基础。模型路由与上下文管理让不同的任务走不同的模型通道聪明地分配上下文窗口既快又省。规则注入与自定义命令把团队规范、个人习惯、常用操作固化到配置里。性能调优与安全检查解决大仓库下的卡顿、误答问题防止敏感信息被当成上下文送出去。接下来按这个顺序一个个拆开讲。2. OpenCode 的配置体系三份文件决定一切2.1 全局配置opencode.json 是主入口OpenCode 的配置体系层级不复杂但优先级容易搞混我先把三份关键文件说清楚。全局配置一般放在用户目录下文件名是opencode.json。它的作用是定义所有项目的默认行为包括默认模型、编辑器集成选项、日志级别、全局的上下文策略等。你可以把它理解为 OpenCode 的“出厂设置”任何项目在没有自己的配置时都按它来。我的全局配置里会放这些内容{ model: { default: default-fast-model }, editor: { integration: enabled, suggestions: inline }, log: { level: info, dir: ~/.opencode/logs }, context: { historyCompression: true, maxHistoryMessages: 20 } }这里有一个容易被忽略的点opencode.json支持 JSONC 格式也就是允许注释和尾逗号。很多从纯 JSON 转过来的开发者下意识以为不能写注释结果要么到处删注释要么写错了格式导致整个文件解析失败。实际上带注释的 JSONC 配置文件在 OpenCode 里是被明确支持的放心写文档注释方便以后维护。2.2 项目级配置.opencode/config.json 的覆盖规则项目级的配置文件位于项目根目录下的.opencode/config.json。它的优先级高于全局配置也就是说同一个配置项项目级写什么最终就用什么全局的会被覆盖掉。项目级配置适合放和当前项目强相关的东西比如{ model: { default: default-balance-model, router: { chat: default-fast-model, agent: default-powerful-model } }, rules: { files: [.opencode/rules/] }, commands: { review: { prompt: 请以资深 reviewer 的视角审查当前变更侧重可维护性和边界条件。, scope: git diff --cached } }, index: { include: [src, lib], exclude: [node_modules, dist, build, .git] } }这里要特别提醒一个容易踩的坑项目级配置的 JSONC 注释和全局配置一样可以写但要注意 BOM字节顺序标记问题。我曾经用一个 Windows 上的编辑器保存 config.json结果文件开头多了个 BOM 字符OpenCode 启动时直接报“配置文件解析失败”。排查了半天才发现是编辑器默认保存格式的问题。建议用编辑器设置里 UTF-8 without BOM 保存所有配置文件。2.3 .opencodeignore控制信息获取范围的边界.opencodeignore是另一份被很多人忽视的文件。它的作用和.gitignore类似但目的是告诉 OpenCode哪些文件不该被索引进上下文。默认情况下OpenCode 会读取项目结构、文件内容、Git 历史来辅助生成回答。但是一个 Monorepo 仓库里可能有几百 MB 的构建产物、锁文件、第三方依赖这些东西一旦进入上下文既浪费 token又干扰模型判断。我的典型.opencodeignore长这样# 构建产物 dist/ build/ target/ *.min.js # 依赖目录 node_modules/ vendor/ .pnpm-store/ # 本地环境配置 .env.local .env.*.local # 大型二进制文件 *.zip *.tar *.gz *.bin *.png *.jpg注意.opencodeignore和.gitignore是两套独立体系不要把.gitignore直接复制成.opencodeignore。git 忽略是为了不提交文件opencode 忽略是为了不让 AI 读取文件两者的目标不一样。比如.env.example这种文件是应该提交到 git 的但没必要让 AI 读取反过来有些已经被 git 忽略的临时文件也不该进 AI 上下文。最稳妥的做法是根据 OpenCode 的实际使用场景单独维护一份。2.4 配置加载顺序与环境变量替换三份配置全局配置、项目级配置、环境变量的加载顺序是固定的OpenCode 启动时先读全局配置再读项目级配置合并最后用环境变量覆盖可覆盖的字段。也就是说环境变量的优先级最高项目级次之全局最低。环境变量在配置里可以用${VAR_NAME}的语法引用。这个特性特别适合处理不同机器上的差异化设置。举个例子我自己有一台本机和一台远程开发机模型供应商的 API Key 不会写在配置文件里而是通过环境变量注入{ model: { provider: { baseUrl: ${LLM_API_BASE}, apiKey: ${LLM_API_KEY} } } }这样做的好处很明显配置文件可以放进版本库共享给团队但密钥只存在于每个开发者的环境变量里避免密钥泄露。另一个环境变量替换的典型用途是区分“开发模式”和“生产模式”。我见过一个团队在 CI 流水里用OPENCODE_MODEci控制 OpenCode 的日志级别和并发数平时本地开发则用默认值一套配置通吃。3. 模型路由与上下文窗口调优让每类任务走最合适的通道3.1 为什么“一个模型走天下”既慢又贵大多数 AI 编程助手的默认行为是把所有请求都发给同一个模型。这个设计图省事但代价不小。排名靠前的大模型能力确实强但响应时间也更长单位 token 的价格也更高。你用模型去生成一段“给变量起名”的建议和让它重构整个模块的架构出力的需求完全不一样花同样的钱和时间那就亏了。OpenCode 支持按任务类型做模型路由这是我觉得它值得配置的最大理由之一。你可以为 chat对话、edit内联编辑、agent自主代理、commit提交信息生成分别指定不同的模型通道。下面是我目前在项目里实际使用的一组路由规则{ model: { default: default-balance-model, router: { chat: { model: default-fast-model, reasoning: disabled }, edit: { model: default-balance-model, reasoning: auto }, agent: { model: default-powerful-model, reasoning: enabled, maxSteps: 30 }, commit: { model: default-fast-model, prompt: 生成简洁的 conventional commit 信息 } } } }这样配置完之后日常对话和 commit 信息用快速模型响应基本在秒级而 agent 类的自主编码任务用最强模型允许更长推理时间。整体体验是该快的时候快该聪明的时候聪明。3.2 更细粒度的文件级路由规则除了按任务类型路由OpenCode 还支持按文件路径或语言类型来分配模型。这个功能在混合技术栈的项目里特别有用。举个例子一个仓库里既有 Python 后端又有 TypeScript 前端还有 SQL 脚本和 YAML 配置。不同语言对模型的要求其实不太一样生成 SQL 的工具类和写一个 React 组件对上下文的敏感度差很远。你可以这样配置{ model: { routingRules: [ { match: src/main/**.java, model: default-powerful-model, reason: Java 核心业务代码质量要求高 }, { match: *.test.ts, model: default-fast-model, reason: 单测代码相对模式化快的就够 }, { match: *.md, model: default-fast-model, reason: 文档生成不需要太强推理 } ] } }每个路由规则还带一个reason字段来说明原因这个字段不是为了给人看的而是 OpenCode 在决策时参考的上下文。我个人的体会是写明 reason 之后路由的准确率会明显提升模型知道“为什么这个文件要用强模型”它就会更积极地调用推理能力。3.3 上下文窗口预算怎么管上下文窗口是 AI 编程助手里最稀缺的资源。一个模型能处理的 token 总量是有限的你把历史对话、当前文件、项目结构、Git 状态全都塞进去很快就把窗口占完了模型开始“忘记”前面的指令。OpenCode 有几个配置项专门管理这事{ context: { maxContextTokens: 16000, historyCompression: true, maxHistoryMessages: 20, fileInclusion: smart, ignoreLargeFiles: true, largeFileThresholdTokens: 4000 } }参数说明如下maxContextTokens单次请求最多使用的上下文 token 数超过部分会触发裁剪策略。设置为 16000 是一个比较保守的值既能保证质量又能控制成本。historyCompression开启后会将早期的对话消息做摘要压缩而不是原样保留。实测下来30 轮以上的长对话压缩后模型回答质量没有明显下降但 token 消耗少了一半以上。fileInclusion设置成smart之后OpenCode 不会把所有打开的文件都塞进上下文而是根据当前代码的 import 关系、变量引用等自动判断哪些文件最相关。ignoreLargeFiles和largeFileThresholdTokens超过 4000 token 的巨型文件默认不进上下文。需要时可以用file语法手动引用避免让模型在一个几千行的文件里大海捞针。3.4 成本与速率的可视化控制配置了模型路由之后成本控制就有了抓手。OpenCode 支持设置每分钟请求数上限和每日消耗预算。这个功能个人用可能感受不深但团队接入时非常重要防止某个成员跑个 agent 任务把一整天的预算在十分钟内烧光。{ cost: { maxRequestsPerMinute: 20, dailyBudget: 8.0, currency: USD, alerts: { thresholdPercent: 80, notify: terminal } } }我自己的习惯是设置 80% 的阈值提醒到 80% 时终端会提示“当前额度已用掉八成”这样还能来得及收敛任务而不是等到预算耗尽才发现。同时把maxRequestsPerMinute设置成一个略低于服务端限制的值能有效避免触发限流导致的连锁重试。4. 把团队规范固化进流程项目规则与自定义命令的实战写法4.1 rules 文件让 AI 从一开始就按你的规矩来AI 编程助手生成的代码风格和你团队的既定规范之间天然存在偏差。与其每次生成后再人工纠正不如直接把规则写进配置文件让模型在生成时就看到这些约束。OpenCode 支持两种规则注入方式一种是在配置文件的rules数组里直接写规则文本另一种是通过rules.files指定一个规则目录目录下的所有.md或.txt文件都会按顺序被加载。我的项目里习惯用目录方式因为规则会越来越多拆成文件好维护。比如.opencode/rules/目录下放这几个文件style.md代码风格约定errors.md常见错误规避项security.md安全红线architecture.md模块划分等架构约束style.md里的内容举例## 命名风格 - 变量名使用 camelCase类名使用 PascalCase - 常量使用 UPPER_SNAKE_CASE - bool 变量开始用 is/has/can 前缀 ## 函数设计 - 函数应该短小一个函数只做一件事 - 超过 50 行时考虑拆分为多个私有方法 - 禁止使用 any 类型TypeScript 代码 ## 其他 - 所有对外 API 需要写 JSDoc 注释 - import 顺序内置模块、第三方模块、本地模块每组之间空一行需要说明的是规则文件的加载顺序是有讲究的。OpenCode 会先加载通用规则再加载项目规则同优先级下按文件名字母序排列。排在后面的规则优先级更高如果两个规则冲突后面的覆盖前面的。这可以让你在项目级规则里对全局规则做局部修正。4.2 自定义命令把重复操作压缩成一个斜杠OpenCode 的自定义命令slash commands是效率提升最直接的功能。它允许你把一段复杂的提示词和可选的命令管道绑定为一个短命令在对话框输入/命令名即可触发。在我日常工作中最常用的是这几个自定义命令{ commands: { review: { prompt: 你是一位资深代码审查者。请审查当前 Git 变更输出问题列表、严重级别、修改建议。优先关注会导致运行时异常、并发安全、数据一致性的问题。, scope: git diff --cached }, commit: { prompt: 根据当前 git diff 生成提交信息使用 conventional commit 格式。控制在 72 字符以内描述变更动机而非仅是变更内容。, scope: git diff --cached, apply: suggest }, explain: { prompt: 请把选中的代码用通俗的比喻向一个非程序员解释清楚先解释整体职责再逐段拆解最后指出你发现的潜在问题。, scope: selection } } }/review配了git diff --cached意味着它会自动读取暂存区的变更不需要你手动复制代码。/commit的apply设为suggest表示生成的 commit 信息只作为建议展示不会直接写入避免它生成不合适的 commit 说明。/explain则绑定当前选中的代码适合快速理解一段陌生代码。这里有一个小原则命令的 prompt 里要有明确的输出格式要求。只写“帮我审查代码”它可能给你一段作文式的泛泛而谈写清楚“输出问题列表、严重级别、修改建议”它就老老实实给你结构化结果。这些格式要求都是从实际使用中琢磨出来的。4.3 用 hooks 把配置推进到工作流每一个环节如果你对自动化有更高的要求OpenCode 还支持 hooks——在特定事件发生时执行外部命令或脚本。这个功能的想象空间很大。我最常用的两个 hooks一个是在BeforeCreateFile时触发模板检查。团队规定所有 React 组件文件必须以index.tsx加styles.ts的结构创建这个 hooks 会检查新文件名是否符合约定不符合就自动中断创建并提示原因。另一个是在AfterChatResponse时把对话摘要写入团队的日志文件方便周报时查看 AI 辅助情况。摘要是模型生成的不会包含原始代码全文避免信息过载。{ hooks: { BeforeCreateFile: { command: sh scripts/check-file-template.sh, timeout: 5000 }, AfterChatResponse: { command: sh scripts/log-ai-usage.sh, timeout: 3000 } } }hooks 的执行是同步阻塞式的如果你的命令卡住了OpenCode 的交互会被耽误所以每个 hook 都必须设置合理的 timeout。我个人建议控制在 5 秒以内。5. 性能调优大仓库下不卡不崩不乱答5.1 索引进度与范围控制OpenCode 为了在回答时能引用项目里相关文件的内容会在本地建一个语义索引。这个索引在大型仓库里是性能的最大瓶颈。默认情况下它会尝试索引整个项目包括各种你不会想让它看的目录。我在一个几万文件的老仓库里第一次跑 OpenCode索引建了十几分钟还没结束编辑器都跟着卡。后来我意识到必须限制索引范围{ index: { include: [src, lib, tests], exclude: [node_modules, dist, build, .git, coverage, docs/api], maxFileSize: 1MB, useGitignore: false } }useGitignore这个选项默认是false很多人以为索引会自动排除.gitignore里的路径其实不会。如果你想要这个行为需要显式开启或者像上面那样手动配置 exclude。这里的配置稍微有点反直觉但理解了就很好控制。5.2 缓存的命中率是流畅度的关键OpenCode 会对已生成的代码块、嵌入向量、模型响应做多级缓存。默认缓存策略足够应付大多数场景但在大仓库下有几个参数值得调{ performance: { semanticCache: { enabled: true, size: 1GB, ttlHours: 24 }, compression: fast, maxParallelRequests: 4, responseStreaming: true } }maxParallelRequests控制同时发出的模型请求数设得太高容易触发限流设得太低则多任务时排队明显。我的经验值是 4 到 6根据你使用的是什么网络环境和服务商的速率限制来定。responseStreaming保持开启这样生成结果时是逐步吐出的体验上比一次等到底快很多。另外有个小技巧如果你经常在固定仓库工作可以考虑把缓存目录映射到内存盘比如 Linux 下放到/dev/shm/opencode-cache。实测下来语义缓存的命中响应时间可以从几百毫秒降到几十毫秒体感非常明显。不过这属于偏门玩法普通用户不必强求。5.3 日志级别与卡顿问题的定位手段大仓库卡顿的原因很多如果只是“感觉卡”却没有数据支撑很难定位问题。OpenCode 的日志配置是我排查问题的第一站。{ log: { level: debug, dir: /tmp/opencode-logs, truncate: true, maxFiles: 5 } }把日志级别调到debug之后每个请求的处理时间、token 消耗、上下文裁剪操作都会记录到文件。如果你发现某次对话延迟特别高去看日志里对应时间段的请求通常能发现是上下文里塞了某个巨大的文件触发了耗时的压缩处理。这时候你就知道该在.opencodeignore里排除什么了。调优完毕把日志级别调回info就好debug 日志量大长期开着会额外消耗磁盘和性能。maxFiles设置为 5 份轮转防止日志文件无限膨胀。6. 安全防线敏感信息保护与审计配置6.1 敏感信息过滤别把密钥送进上下文这是我在团队里最强调的一部分配置。很多开发者把 AI 编程助手当成“会读代码的同事”但它背后是模型推理服务你的代码和上下文实际上会发送出去。如果你的代码里有明文密钥、数据库连接串、内部 API Token这些东西一旦进入模型上下文就等于默认送给了第三方。OpenCode 提供了一套内置的敏感信息脱敏机制同时支持自定义规则。我建议至少配置以下几类{ security: { sensitivePatterns: [ AKIA[0-9A-Z]{16}, sk-[a-zA-Z0-9]{20,}, password\\s*[:]\\s*., api[_-]?key\\s*[:]\\s*., -----BEGIN (RSA|EC|OPENSSH) PRIVATE KEY----- ], actions: [mask, block] } }mask表示将匹配到的内容替换为类似的脱敏占位符block表示如果检测到敏感信息则直接拒绝该请求。我的建议是身份验证类的密钥用 block普通配置里出现的密码字段用 mask。因为如果一律 block可能误伤一些本来就是示例配置的文本但真正的密钥一旦泄露后果比误伤严重得多。6.2 交互消息的脱敏处理敏感信息过滤不只是对代码内容生效对话消息本身也需要处理。很多人喜欢在对话里粘贴一段包含真实数据的 JSON 日志结果日志里正好有手机号、身份证号之类的个人数据。OpenCode 支持在发送前对消息做正则脱敏{ security: { messageSanitization: true, sanitizePatterns: [ 1[3-9][0-9]{9}, [0-9]{17}[0-9Xx] ] } }这两条是常见的手机号和身份证号正则可以按你的实际业务调整。开启之后发出去的 prompt 会被替换成脱敏形式既不影响 AI 理解数据结构又不会泄露个人数据。6.3 审计日志留痕但不留全文如果一个团队里多人使用 AI 编程助手审计日志是必须考虑的。但审计日志记录什么、不记录什么需要想清楚。我的原则是记录元数据不记录全文——谁、什么时候、调用了什么命令、用了哪个模型、消耗了多少 token这些记下来至于具体的 prompt 和模型返回不加进审计范围因为里面可能包含代码片段和业务信息。{ audit: { enabled: true, logPath: logs/opencode-audit.jsonl, include: [user, timestamp, command, model, tokens, status], maskPrompts: true } }maskPrompts设为true之后审计日志里不会保存 prompt 正文。如果遇到代码泄露纠纷或者需要回溯操作至少能定位是谁在什么时候做了什么操作有没有触发安全策略为后续调查提供线索。7. 踩坑实录配置中最容易翻车的四个细节7.1 JSONC 注释的格式陷阱前面提到 OpenCode 支持 JSONC但这里有个不容易察觉的坑JSONC 支持注释但不支持未加引号的键名也不支持单引号字符串。某些项目根目录里已经有其他工具生成的 JSON 文件可能用的是宽松 JSON5 风格写着写着就容易混用。真实遇到过的案例是一位同事从网上复制了一段配置里面出现了model: xxx这种单引号写法OpenCode 加载时直接提示解析失败。折腾十几分钟才发现是引号问题。建议在写配置文件时用 IDE 的 JSONC 语法检查插件开启实时校验避免这种低级错误。7.2 相对路径的基准目录问题配置文件里的相对路径基准目录到底是配置文件所在目录还是项目根目录这个很容易搞混。OpenCode 的规则是路径基准是项目根目录而不是配置文件所在目录。也就是说在.opencode/config.json里写./src/app实际指向的是项目根/src/app而不是项目根/.opencode/src/app。这个设计本身挺合理但第一次配置的时候几乎人人都中招。我后来总结了个规律凡是和项目内容相关的路径index 范围、rules 目录、hook 脚本都是以项目根为基准的凡是和 OpenCode 自身数据相关的路径缓存、日志、审计文件都是可以带用户目录路径的绝对路径或相对于用户主目录的路径。7.3 规则冲突时的优先级误判项目里有全局规则、项目规则、内联指令三套东西它们之间的优先级很容易造成困惑。我经历过一个实际场景全局规则里有一条“禁止在代码注释中使用中文”但项目组为了非中文母语的海外同事理解要求在关键算法附近加中文注释。结果生成的代码一直在两种风格之间横跳最后排查发现是全局规则和项目规则都写在了同一个rules数组里靠顺序覆盖但全局规则排在项目规则后面反而把项目规则覆盖了。OpenCode 的实际优先级是内联指令 项目规则 全局规则。你想让项目规则覆盖全局规则必须把全局规则放在独立的全局配置里项目规则放在项目配置里让层级关系来决定优先级而不是靠同一层级下的顺序。这是配置里最隐蔽的坑。7.4 版本升级导致的配置项失效OpenCode 迭代速度不慢升级后某些配置项会改名字、改语义甚至被移除。最典型的是有一次我升级完之后自定义命令全部不生效了终端里没有任何报错只是命令完全没反应。检查才发现旧版本的slashCommands字段在升级后被改成了commands而旧字段被静默忽略不提示废弃也不报错。这提醒我一个习惯每次升级 OpenCode 之后最好扫一眼配置文件的 schema 提示或者在终端运行一次配置校验命令。如果配置项被废弃官方一般会在校验结果里给出警告。别等到命令失灵了再排查那通常要浪费不少时间。8. 最后分享一点我的使用习惯还有一个值得单独说的小技巧关于配置的版本管理。OpenCode 的项目配置建议提交到版本库方便团队同步。但全局配置里要多留一个心眼——它可能包含你的个人习惯、私有密钥引用、以及针对某台机器的特殊设置提交前先检查有没有把敏感信息带进去。我的做法是把全局配置拆成两个文件一个不包含任何敏感信息的默认配置提交到个人配置仓库另一个包含本地路径和密钥的配置单独留在~/.opencode/opencode.local.json里并加入.gitignore。配置这件事不怕折腾怕的是没有方向。建议不要一次把所有功能全部打开先挑一两个最影响你生产力的点去调比如先把模型路由和上下文预算配置好用两周感受变化再逐步加规则、加 hooks。这样每一步的反馈都是明确的出了问题也知道是哪部分改动引起的。OpenCode 的高级配置本质上是一个持续磨合的过程你对它越了解它就越贴合你的工作方式。 
长河君 · 2026/10/21 5:20:09 · 阅读 1.2k OpenCode高级配置实战：模型路由、上下文管理与团队规则注入
说句实话我最早接触 OpenCode AI 编程助手时装完默认配置跑起来感觉就是个稍微聪明点的自动补全。直到某次被一个几百行的跨文件重构任务逼到墙角才开始认真研究它的高级配置改完直接真香。同样是这个工具默认配置和精细配置过的版本用起来完全是两种东西。很多人说某个 AI 编程助手“不好用”往往不是模型不行而是配置没有跟上去。这篇文章不聊基础操作专门聊高级配置——那些不会写在“欢迎页”里、但真正决定效率上限的选项包括配置体系、模型路由、上下文管理、规则注入、性能与安全调优以及我实际踩过的坑。1. 默认配置能用但高级配置才是分水岭1.1 默认配置到底缺了什么OpenCode 装完以后默认配置基本是“开箱即用”的思路一个通用的对话模型、自动补全、基础的编辑器集成。这套配置足够你应付日常的代码生成、解释、改 bug但如果你是个每天要处理大量真实业务的开发者很快就会碰到几个绕不开的瓶颈。第一个瓶颈是模型选择太单一。默认配置通常只指定了一个主力模型但实际开发里写一个 git commit 信息、做一次代码审查、解释一段复杂逻辑、生成一大块脚手架代码这些任务的难度和对延迟的容忍度完全不一样。用同一个模型处理所有事情要么钱花得冤枉要么等得心烦。第二个瓶颈是上下文窗口的浪费。OpenCode 默认会把当前文件、选中的代码、最近的对话历史一起塞给模型。项目小的时候无所谓一旦你在一个几万行代码的仓库里工作默认策略会把大量无关的文件片段也带进去模型反而抓不住重点回答质量肉眼可见地下降。第三个瓶颈是规则缺失。默认配置不懂你的团队规范缩进用几个空格、变量命名风格、禁止直接提交密钥、接口调用的统一封装方式……这些如果不通过配置固化到 OpenCode 的行为里每次生成代码都需要你手动纠正那体验就和“人工调教 AI”没什么区别了。1.2 什么样的人值得投入时间做高级配置如果你只是偶尔用 AI 助手改个脚本那确实不需要折腾高级配置默认的够用。但下面这几类人我强烈建议认真读下去在大中型项目里日常使用 OpenCode 的开发者。仓库一大上下文管理和模型路由的收益立竿见影。对代码质量和安全有要求的团队。规则注入和敏感信息过滤能帮你在源头减少 bad case。用 OpenCode 跑自动化任务的人。自定义命令和 hooks 能把重复操作从几分钟压缩到几秒。对 API 成本敏感的用户。通过模型路由把简单任务分给便宜模型一个月下来省下的费用肉眼可见。高级配置听起来“高级”其实不是让你去改 OpenCode 的源码而是把它的配置能力吃透。后面每个章节我都会给出能直接落地的配置片段和解释你可以按需取用。1.3 高级配置的四大核心方向在深入细节之前先给你一张地图避免一头扎进配置文件里迷路。OpenCode 的高级配置基本围绕四个方向展开这也是我和身边开发者验证之后公认最出效果的维度配置体系与优先级搞清楚全局配置、项目配置、环境变量之间怎么叠加、覆盖这是所有高级操作的基础。模型路由与上下文管理让不同的任务走不同的模型通道聪明地分配上下文窗口既快又省。规则注入与自定义命令把团队规范、个人习惯、常用操作固化到配置里。性能调优与安全检查解决大仓库下的卡顿、误答问题防止敏感信息被当成上下文送出去。接下来按这个顺序一个个拆开讲。2. OpenCode 的配置体系三份文件决定一切2.1 全局配置opencode.json 是主入口OpenCode 的配置体系层级不复杂但优先级容易搞混我先把三份关键文件说清楚。全局配置一般放在用户目录下文件名是opencode.json。它的作用是定义所有项目的默认行为包括默认模型、编辑器集成选项、日志级别、全局的上下文策略等。你可以把它理解为 OpenCode 的“出厂设置”任何项目在没有自己的配置时都按它来。我的全局配置里会放这些内容{ model: { default: default-fast-model }, editor: { integration: enabled, suggestions: inline }, log: { level: info, dir: ~/.opencode/logs }, context: { historyCompression: true, maxHistoryMessages: 20 } }这里有一个容易被忽略的点opencode.json支持 JSONC 格式也就是允许注释和尾逗号。很多从纯 JSON 转过来的开发者下意识以为不能写注释结果要么到处删注释要么写错了格式导致整个文件解析失败。实际上带注释的 JSONC 配置文件在 OpenCode 里是被明确支持的放心写文档注释方便以后维护。2.2 项目级配置.opencode/config.json 的覆盖规则项目级的配置文件位于项目根目录下的.opencode/config.json。它的优先级高于全局配置也就是说同一个配置项项目级写什么最终就用什么全局的会被覆盖掉。项目级配置适合放和当前项目强相关的东西比如{ model: { default: default-balance-model, router: { chat: default-fast-model, agent: default-powerful-model } }, rules: { files: [.opencode/rules/] }, commands: { review: { prompt: 请以资深 reviewer 的视角审查当前变更侧重可维护性和边界条件。, scope: git diff --cached } }, index: { include: [src, lib], exclude: [node_modules, dist, build, .git] } }这里要特别提醒一个容易踩的坑项目级配置的 JSONC 注释和全局配置一样可以写但要注意 BOM字节顺序标记问题。我曾经用一个 Windows 上的编辑器保存 config.json结果文件开头多了个 BOM 字符OpenCode 启动时直接报“配置文件解析失败”。排查了半天才发现是编辑器默认保存格式的问题。建议用编辑器设置里 UTF-8 without BOM 保存所有配置文件。2.3 .opencodeignore控制信息获取范围的边界.opencodeignore是另一份被很多人忽视的文件。它的作用和.gitignore类似但目的是告诉 OpenCode哪些文件不该被索引进上下文。默认情况下OpenCode 会读取项目结构、文件内容、Git 历史来辅助生成回答。但是一个 Monorepo 仓库里可能有几百 MB 的构建产物、锁文件、第三方依赖这些东西一旦进入上下文既浪费 token又干扰模型判断。我的典型.opencodeignore长这样# 构建产物 dist/ build/ target/ *.min.js # 依赖目录 node_modules/ vendor/ .pnpm-store/ # 本地环境配置 .env.local .env.*.local # 大型二进制文件 *.zip *.tar *.gz *.bin *.png *.jpg注意.opencodeignore和.gitignore是两套独立体系不要把.gitignore直接复制成.opencodeignore。git 忽略是为了不提交文件opencode 忽略是为了不让 AI 读取文件两者的目标不一样。比如.env.example这种文件是应该提交到 git 的但没必要让 AI 读取反过来有些已经被 git 忽略的临时文件也不该进 AI 上下文。最稳妥的做法是根据 OpenCode 的实际使用场景单独维护一份。2.4 配置加载顺序与环境变量替换三份配置全局配置、项目级配置、环境变量的加载顺序是固定的OpenCode 启动时先读全局配置再读项目级配置合并最后用环境变量覆盖可覆盖的字段。也就是说环境变量的优先级最高项目级次之全局最低。环境变量在配置里可以用${VAR_NAME}的语法引用。这个特性特别适合处理不同机器上的差异化设置。举个例子我自己有一台本机和一台远程开发机模型供应商的 API Key 不会写在配置文件里而是通过环境变量注入{ model: { provider: { baseUrl: ${LLM_API_BASE}, apiKey: ${LLM_API_KEY} } } }这样做的好处很明显配置文件可以放进版本库共享给团队但密钥只存在于每个开发者的环境变量里避免密钥泄露。另一个环境变量替换的典型用途是区分“开发模式”和“生产模式”。我见过一个团队在 CI 流水里用OPENCODE_MODEci控制 OpenCode 的日志级别和并发数平时本地开发则用默认值一套配置通吃。3. 模型路由与上下文窗口调优让每类任务走最合适的通道3.1 为什么“一个模型走天下”既慢又贵大多数 AI 编程助手的默认行为是把所有请求都发给同一个模型。这个设计图省事但代价不小。排名靠前的大模型能力确实强但响应时间也更长单位 token 的价格也更高。你用模型去生成一段“给变量起名”的建议和让它重构整个模块的架构出力的需求完全不一样花同样的钱和时间那就亏了。OpenCode 支持按任务类型做模型路由这是我觉得它值得配置的最大理由之一。你可以为 chat对话、edit内联编辑、agent自主代理、commit提交信息生成分别指定不同的模型通道。下面是我目前在项目里实际使用的一组路由规则{ model: { default: default-balance-model, router: { chat: { model: default-fast-model, reasoning: disabled }, edit: { model: default-balance-model, reasoning: auto }, agent: { model: default-powerful-model, reasoning: enabled, maxSteps: 30 }, commit: { model: default-fast-model, prompt: 生成简洁的 conventional commit 信息 } } } }这样配置完之后日常对话和 commit 信息用快速模型响应基本在秒级而 agent 类的自主编码任务用最强模型允许更长推理时间。整体体验是该快的时候快该聪明的时候聪明。3.2 更细粒度的文件级路由规则除了按任务类型路由OpenCode 还支持按文件路径或语言类型来分配模型。这个功能在混合技术栈的项目里特别有用。举个例子一个仓库里既有 Python 后端又有 TypeScript 前端还有 SQL 脚本和 YAML 配置。不同语言对模型的要求其实不太一样生成 SQL 的工具类和写一个 React 组件对上下文的敏感度差很远。你可以这样配置{ model: { routingRules: [ { match: src/main/**.java, model: default-powerful-model, reason: Java 核心业务代码质量要求高 }, { match: *.test.ts, model: default-fast-model, reason: 单测代码相对模式化快的就够 }, { match: *.md, model: default-fast-model, reason: 文档生成不需要太强推理 } ] } }每个路由规则还带一个reason字段来说明原因这个字段不是为了给人看的而是 OpenCode 在决策时参考的上下文。我个人的体会是写明 reason 之后路由的准确率会明显提升模型知道“为什么这个文件要用强模型”它就会更积极地调用推理能力。3.3 上下文窗口预算怎么管上下文窗口是 AI 编程助手里最稀缺的资源。一个模型能处理的 token 总量是有限的你把历史对话、当前文件、项目结构、Git 状态全都塞进去很快就把窗口占完了模型开始“忘记”前面的指令。OpenCode 有几个配置项专门管理这事{ context: { maxContextTokens: 16000, historyCompression: true, maxHistoryMessages: 20, fileInclusion: smart, ignoreLargeFiles: true, largeFileThresholdTokens: 4000 } }参数说明如下maxContextTokens单次请求最多使用的上下文 token 数超过部分会触发裁剪策略。设置为 16000 是一个比较保守的值既能保证质量又能控制成本。historyCompression开启后会将早期的对话消息做摘要压缩而不是原样保留。实测下来30 轮以上的长对话压缩后模型回答质量没有明显下降但 token 消耗少了一半以上。fileInclusion设置成smart之后OpenCode 不会把所有打开的文件都塞进上下文而是根据当前代码的 import 关系、变量引用等自动判断哪些文件最相关。ignoreLargeFiles和largeFileThresholdTokens超过 4000 token 的巨型文件默认不进上下文。需要时可以用file语法手动引用避免让模型在一个几千行的文件里大海捞针。3.4 成本与速率的可视化控制配置了模型路由之后成本控制就有了抓手。OpenCode 支持设置每分钟请求数上限和每日消耗预算。这个功能个人用可能感受不深但团队接入时非常重要防止某个成员跑个 agent 任务把一整天的预算在十分钟内烧光。{ cost: { maxRequestsPerMinute: 20, dailyBudget: 8.0, currency: USD, alerts: { thresholdPercent: 80, notify: terminal } } }我自己的习惯是设置 80% 的阈值提醒到 80% 时终端会提示“当前额度已用掉八成”这样还能来得及收敛任务而不是等到预算耗尽才发现。同时把maxRequestsPerMinute设置成一个略低于服务端限制的值能有效避免触发限流导致的连锁重试。4. 把团队规范固化进流程项目规则与自定义命令的实战写法4.1 rules 文件让 AI 从一开始就按你的规矩来AI 编程助手生成的代码风格和你团队的既定规范之间天然存在偏差。与其每次生成后再人工纠正不如直接把规则写进配置文件让模型在生成时就看到这些约束。OpenCode 支持两种规则注入方式一种是在配置文件的rules数组里直接写规则文本另一种是通过rules.files指定一个规则目录目录下的所有.md或.txt文件都会按顺序被加载。我的项目里习惯用目录方式因为规则会越来越多拆成文件好维护。比如.opencode/rules/目录下放这几个文件style.md代码风格约定errors.md常见错误规避项security.md安全红线architecture.md模块划分等架构约束style.md里的内容举例## 命名风格 - 变量名使用 camelCase类名使用 PascalCase - 常量使用 UPPER_SNAKE_CASE - bool 变量开始用 is/has/can 前缀 ## 函数设计 - 函数应该短小一个函数只做一件事 - 超过 50 行时考虑拆分为多个私有方法 - 禁止使用 any 类型TypeScript 代码 ## 其他 - 所有对外 API 需要写 JSDoc 注释 - import 顺序内置模块、第三方模块、本地模块每组之间空一行需要说明的是规则文件的加载顺序是有讲究的。OpenCode 会先加载通用规则再加载项目规则同优先级下按文件名字母序排列。排在后面的规则优先级更高如果两个规则冲突后面的覆盖前面的。这可以让你在项目级规则里对全局规则做局部修正。4.2 自定义命令把重复操作压缩成一个斜杠OpenCode 的自定义命令slash commands是效率提升最直接的功能。它允许你把一段复杂的提示词和可选的命令管道绑定为一个短命令在对话框输入/命令名即可触发。在我日常工作中最常用的是这几个自定义命令{ commands: { review: { prompt: 你是一位资深代码审查者。请审查当前 Git 变更输出问题列表、严重级别、修改建议。优先关注会导致运行时异常、并发安全、数据一致性的问题。, scope: git diff --cached }, commit: { prompt: 根据当前 git diff 生成提交信息使用 conventional commit 格式。控制在 72 字符以内描述变更动机而非仅是变更内容。, scope: git diff --cached, apply: suggest }, explain: { prompt: 请把选中的代码用通俗的比喻向一个非程序员解释清楚先解释整体职责再逐段拆解最后指出你发现的潜在问题。, scope: selection } } }/review配了git diff --cached意味着它会自动读取暂存区的变更不需要你手动复制代码。/commit的apply设为suggest表示生成的 commit 信息只作为建议展示不会直接写入避免它生成不合适的 commit 说明。/explain则绑定当前选中的代码适合快速理解一段陌生代码。这里有一个小原则命令的 prompt 里要有明确的输出格式要求。只写“帮我审查代码”它可能给你一段作文式的泛泛而谈写清楚“输出问题列表、严重级别、修改建议”它就老老实实给你结构化结果。这些格式要求都是从实际使用中琢磨出来的。4.3 用 hooks 把配置推进到工作流每一个环节如果你对自动化有更高的要求OpenCode 还支持 hooks——在特定事件发生时执行外部命令或脚本。这个功能的想象空间很大。我最常用的两个 hooks一个是在BeforeCreateFile时触发模板检查。团队规定所有 React 组件文件必须以index.tsx加styles.ts的结构创建这个 hooks 会检查新文件名是否符合约定不符合就自动中断创建并提示原因。另一个是在AfterChatResponse时把对话摘要写入团队的日志文件方便周报时查看 AI 辅助情况。摘要是模型生成的不会包含原始代码全文避免信息过载。{ hooks: { BeforeCreateFile: { command: sh scripts/check-file-template.sh, timeout: 5000 }, AfterChatResponse: { command: sh scripts/log-ai-usage.sh, timeout: 3000 } } }hooks 的执行是同步阻塞式的如果你的命令卡住了OpenCode 的交互会被耽误所以每个 hook 都必须设置合理的 timeout。我个人建议控制在 5 秒以内。5. 性能调优大仓库下不卡不崩不乱答5.1 索引进度与范围控制OpenCode 为了在回答时能引用项目里相关文件的内容会在本地建一个语义索引。这个索引在大型仓库里是性能的最大瓶颈。默认情况下它会尝试索引整个项目包括各种你不会想让它看的目录。我在一个几万文件的老仓库里第一次跑 OpenCode索引建了十几分钟还没结束编辑器都跟着卡。后来我意识到必须限制索引范围{ index: { include: [src, lib, tests], exclude: [node_modules, dist, build, .git, coverage, docs/api], maxFileSize: 1MB, useGitignore: false } }useGitignore这个选项默认是false很多人以为索引会自动排除.gitignore里的路径其实不会。如果你想要这个行为需要显式开启或者像上面那样手动配置 exclude。这里的配置稍微有点反直觉但理解了就很好控制。5.2 缓存的命中率是流畅度的关键OpenCode 会对已生成的代码块、嵌入向量、模型响应做多级缓存。默认缓存策略足够应付大多数场景但在大仓库下有几个参数值得调{ performance: { semanticCache: { enabled: true, size: 1GB, ttlHours: 24 }, compression: fast, maxParallelRequests: 4, responseStreaming: true } }maxParallelRequests控制同时发出的模型请求数设得太高容易触发限流设得太低则多任务时排队明显。我的经验值是 4 到 6根据你使用的是什么网络环境和服务商的速率限制来定。responseStreaming保持开启这样生成结果时是逐步吐出的体验上比一次等到底快很多。另外有个小技巧如果你经常在固定仓库工作可以考虑把缓存目录映射到内存盘比如 Linux 下放到/dev/shm/opencode-cache。实测下来语义缓存的命中响应时间可以从几百毫秒降到几十毫秒体感非常明显。不过这属于偏门玩法普通用户不必强求。5.3 日志级别与卡顿问题的定位手段大仓库卡顿的原因很多如果只是“感觉卡”却没有数据支撑很难定位问题。OpenCode 的日志配置是我排查问题的第一站。{ log: { level: debug, dir: /tmp/opencode-logs, truncate: true, maxFiles: 5 } }把日志级别调到debug之后每个请求的处理时间、token 消耗、上下文裁剪操作都会记录到文件。如果你发现某次对话延迟特别高去看日志里对应时间段的请求通常能发现是上下文里塞了某个巨大的文件触发了耗时的压缩处理。这时候你就知道该在.opencodeignore里排除什么了。调优完毕把日志级别调回info就好debug 日志量大长期开着会额外消耗磁盘和性能。maxFiles设置为 5 份轮转防止日志文件无限膨胀。6. 安全防线敏感信息保护与审计配置6.1 敏感信息过滤别把密钥送进上下文这是我在团队里最强调的一部分配置。很多开发者把 AI 编程助手当成“会读代码的同事”但它背后是模型推理服务你的代码和上下文实际上会发送出去。如果你的代码里有明文密钥、数据库连接串、内部 API Token这些东西一旦进入模型上下文就等于默认送给了第三方。OpenCode 提供了一套内置的敏感信息脱敏机制同时支持自定义规则。我建议至少配置以下几类{ security: { sensitivePatterns: [ AKIA[0-9A-Z]{16}, sk-[a-zA-Z0-9]{20,}, password\\s*[:]\\s*., api[_-]?key\\s*[:]\\s*., -----BEGIN (RSA|EC|OPENSSH) PRIVATE KEY----- ], actions: [mask, block] } }mask表示将匹配到的内容替换为类似的脱敏占位符block表示如果检测到敏感信息则直接拒绝该请求。我的建议是身份验证类的密钥用 block普通配置里出现的密码字段用 mask。因为如果一律 block可能误伤一些本来就是示例配置的文本但真正的密钥一旦泄露后果比误伤严重得多。6.2 交互消息的脱敏处理敏感信息过滤不只是对代码内容生效对话消息本身也需要处理。很多人喜欢在对话里粘贴一段包含真实数据的 JSON 日志结果日志里正好有手机号、身份证号之类的个人数据。OpenCode 支持在发送前对消息做正则脱敏{ security: { messageSanitization: true, sanitizePatterns: [ 1[3-9][0-9]{9}, [0-9]{17}[0-9Xx] ] } }这两条是常见的手机号和身份证号正则可以按你的实际业务调整。开启之后发出去的 prompt 会被替换成脱敏形式既不影响 AI 理解数据结构又不会泄露个人数据。6.3 审计日志留痕但不留全文如果一个团队里多人使用 AI 编程助手审计日志是必须考虑的。但审计日志记录什么、不记录什么需要想清楚。我的原则是记录元数据不记录全文——谁、什么时候、调用了什么命令、用了哪个模型、消耗了多少 token这些记下来至于具体的 prompt 和模型返回不加进审计范围因为里面可能包含代码片段和业务信息。{ audit: { enabled: true, logPath: logs/opencode-audit.jsonl, include: [user, timestamp, command, model, tokens, status], maskPrompts: true } }maskPrompts设为true之后审计日志里不会保存 prompt 正文。如果遇到代码泄露纠纷或者需要回溯操作至少能定位是谁在什么时候做了什么操作有没有触发安全策略为后续调查提供线索。7. 踩坑实录配置中最容易翻车的四个细节7.1 JSONC 注释的格式陷阱前面提到 OpenCode 支持 JSONC但这里有个不容易察觉的坑JSONC 支持注释但不支持未加引号的键名也不支持单引号字符串。某些项目根目录里已经有其他工具生成的 JSON 文件可能用的是宽松 JSON5 风格写着写着就容易混用。真实遇到过的案例是一位同事从网上复制了一段配置里面出现了model: xxx这种单引号写法OpenCode 加载时直接提示解析失败。折腾十几分钟才发现是引号问题。建议在写配置文件时用 IDE 的 JSONC 语法检查插件开启实时校验避免这种低级错误。7.2 相对路径的基准目录问题配置文件里的相对路径基准目录到底是配置文件所在目录还是项目根目录这个很容易搞混。OpenCode 的规则是路径基准是项目根目录而不是配置文件所在目录。也就是说在.opencode/config.json里写./src/app实际指向的是项目根/src/app而不是项目根/.opencode/src/app。这个设计本身挺合理但第一次配置的时候几乎人人都中招。我后来总结了个规律凡是和项目内容相关的路径index 范围、rules 目录、hook 脚本都是以项目根为基准的凡是和 OpenCode 自身数据相关的路径缓存、日志、审计文件都是可以带用户目录路径的绝对路径或相对于用户主目录的路径。7.3 规则冲突时的优先级误判项目里有全局规则、项目规则、内联指令三套东西它们之间的优先级很容易造成困惑。我经历过一个实际场景全局规则里有一条“禁止在代码注释中使用中文”但项目组为了非中文母语的海外同事理解要求在关键算法附近加中文注释。结果生成的代码一直在两种风格之间横跳最后排查发现是全局规则和项目规则都写在了同一个rules数组里靠顺序覆盖但全局规则排在项目规则后面反而把项目规则覆盖了。OpenCode 的实际优先级是内联指令 项目规则 全局规则。你想让项目规则覆盖全局规则必须把全局规则放在独立的全局配置里项目规则放在项目配置里让层级关系来决定优先级而不是靠同一层级下的顺序。这是配置里最隐蔽的坑。7.4 版本升级导致的配置项失效OpenCode 迭代速度不慢升级后某些配置项会改名字、改语义甚至被移除。最典型的是有一次我升级完之后自定义命令全部不生效了终端里没有任何报错只是命令完全没反应。检查才发现旧版本的slashCommands字段在升级后被改成了commands而旧字段被静默忽略不提示废弃也不报错。这提醒我一个习惯每次升级 OpenCode 之后最好扫一眼配置文件的 schema 提示或者在终端运行一次配置校验命令。如果配置项被废弃官方一般会在校验结果里给出警告。别等到命令失灵了再排查那通常要浪费不少时间。8. 最后分享一点我的使用习惯还有一个值得单独说的小技巧关于配置的版本管理。OpenCode 的项目配置建议提交到版本库方便团队同步。但全局配置里要多留一个心眼——它可能包含你的个人习惯、私有密钥引用、以及针对某台机器的特殊设置提交前先检查有没有把敏感信息带进去。我的做法是把全局配置拆成两个文件一个不包含任何敏感信息的默认配置提交到个人配置仓库另一个包含本地路径和密钥的配置单独留在~/.opencode/opencode.local.json里并加入.gitignore。配置这件事不怕折腾怕的是没有方向。建议不要一次把所有功能全部打开先挑一两个最影响你生产力的点去调比如先把模型路由和上下文预算配置好用两周感受变化再逐步加规则、加 hooks。这样每一步的反馈都是明确的出了问题也知道是哪部分改动引起的。OpenCode 的高级配置本质上是一个持续磨合的过程你对它越了解它就越贴合你的工作方式。