飞鹰二我用 OpenCode 的时间不算短，从一开始只会让它写点单文件脚本，到后来把整个项目的日常重构、改 bug、写测试都交给它，中间隔着的东西其实就是配置。默认配置能跑，但跑得不算聪明；等你真正把模型接入、上下文、工具权限、缓存这几层都调顺之后，它才像是一个真正懂你项目的协作同事。这篇文章把我自己在实际配置里踩过的坑和验证过的参数都整理出来，应该能帮你跳过最绕的一段时间。
1. 先搞清楚 OpenCode 配置体系的加载顺序
OpenCode 说起来是"开箱即用"，但高级配置的第一个门槛不是记参数，而是理解它从哪儿读配置。我第一次配的时候直接在命令行改参数，改完发现下一次启动又被覆盖，折腾了半天才意识到是环境变量优先级更高，这类工具基本都是三层结构：内置默认值、全局用户配置、当前项目配置。
优先级从低到高排列，高优先级会覆盖低优先级。具体来说，内置默认值是最底层，存工具出厂设定；全局配置放在用户主目录下，影响这台机器上所有项目；项目配置放在当前仓库的 .opencode 目录里，只对当前项目生效，且优先级最高。项目配置建议纳入版本管理，团队成员clone下来就能复现同样的行为，但全局配置不要提交到仓库。
我实际用下来的习惯是：全局配置只放跟机器相关的偏好，默认模型、密钥读取方式、日志级别。项目配置放跟业务相关的规则，比如项目说明文件的位置、允许工具访问的目录、需要确认的高风险操作清单。
检查配置到底生效了没有，就一个命令：opencode config show。
另外一个容易忽视的点是 OpenCode 的配置支持环境变量替换，配置里不直接写死密钥，用 ${OPENCODE_API_KEY} 这种方式引用。这样同一个配置文件在不同机器上都能用，密钥也不会跟着配置进版本库。
1.1 配置文件的主结构
详细规划用两个主段落，然后在最后带上表格式结构。
一般不需要设为 0，除非你完全不想它发挥创造力。代码生成任务建议 0～0.3，0.2 是我试过最稳的。top_p 是另一个采样开关，加了 top_p 会让输出更集中在高概率 token 上，但注意 top_p 和 temperature 最好不要同时猛调，两者都改会让结果很难预测。我通常保持 top_p 在 0.9，只微调 temperature。
max_tokens 值得认真算一笔。它限制的是生成侧长度，不是输入侧。如果你让它改一个大型函数，max_tokens 设太小会出现输出突然截断，代码没写完就停了，甚至会让它强行补一个残缺的 return。我按照任务的复杂度分配：单行修复填 2048，小函数重写填 4096，整文件重构填 8192，涉及跨文件生成时填 16384。这不算乱给，因为生成长度超出 max_tokens 是"硬截断"，与其让它截断不如给足空间。
还有个经常被忽略的参数是 stop 序列，也就是生成到某个标记就主动停。比如代码块结束标记 ```，或者特定注释标记。在 OpenCode 里配置 stop 序列能有效防止模型把答案越写越长，尤其是当它被养成"多输出一点显得更负责"的坏习惯时。
2.2 模型选择要与任务类型对齐
OpenCode 本身支持不同厂商的模型，但"能用"跟"好用"是两码事。我自己测过三种类型：通用旗舰模型、代码专用模型、轻量快速模型，结论是它们的分工完全不同。
通用旗舰模型适合处理复杂分析任务，比如从一段模糊的需求描述里理出边界条件，或者解释一个跨模块的调用链。它强在理解力，但响应偏慢、价格偏高，不适合高频的小改动。代码专用模型是日常主力，对语法结构、常见 API 模式更敏感，补全和重构都比较稳。轻量快速模型我一般只开给 IDE 里的行级补全用，因为那种场景要的是快，上下文很小，不需要很强的推理能力。
OpenCode 支持按会话指定模型，这个功能很实用。我会在同一个项目里并行开三个会话，一个用代码专用模型做重构，一个用通用旗舰模型读日志分析故障，另一个用轻量模型做简单填充。这样不会互相干扰，成本也可控。
2.3 接入兼容协议平台时要注意的三个细节
很多自定义平台的地址不是标准路径，要先确认 /v1 路径。我用过一个平台的地址是 https://example.com/api/v1，另一个是 https://example.com/v1，填错直接 404。OpenCode 一般不会自动补路径，所以检查文档时重点看 base_url 的完整写法。
密钥环境变量名也要对得上。OpenCode 里最常见的配置方式是 api_key_env，它读取的是你系统环境变量里那个名字。命名建议统一用 OPENCODE_API_KEY 这种前缀，避免跟其他工具冲突。环境变量设置完之后，记得要新开一个终端窗口再启动 OpenCode，因为旧终端里可能还没加载到新变量。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
3. 上下文工程：决定 AI 是否真懂你的项目
配置完模型接入之后，真正把 OpenCode 从"会写代码"拉高到"懂项目"的是上下文管理，这也是高级配置里最有价值的部分。模型本身不知道你的项目结构，不知道哪些文件是核心逻辑，也不知道哪些目录该忽略。它知道的每一点都来自你喂进去的上下文。
OpenCode 有两种上下文进入路径：一是系统级提示词，每次请求都带；二是自动文件选择，按规则把相关文件的内容拼进请求。系统提示词我建议写得像一份"员工手册"，把项目技术栈、目录规范、禁忌事项写清楚。比如我的某项目提示词里有这么一句："后端代码在 backend/ 目录，新增路由必须带鉴权中间件，修改数据库表结构前先确认迁移脚本存在。"模型真的会照着做。
自动文件选择要克制。不是文件越多越好，上下文窗口是固定大小的，塞进去的内容不是模型本次需要的，反而会稀释注意力。我的经验是认真的用排除规则，把 dist、node_modules、lock 文件这类噪声挡掉，再显式包含架构文档和公共接口定义。你可以在项目配置文件里看到一个 context.exclude 列表，它跟 .gitignore 的语法一致，但要注意排除规则只影响自动拼接，不影响你主动指定的文件。
3.1 上下文预算怎么算
我给自己定的输入预算原则是把单次请求的上下文尽量控制在模型窗口的三分之二以内，留下给输出和思考的空间。举个例子，某模型窗口是 32k token，我会把自动上下文压到 20k 左右，剩余部分留给本轮对话历史和新指令。如果自动上下文太多，我宁可部分排除某些没啥用的文档，也不要让它超窗口。
这里有个很实用的技巧：OpenCode 会在配置里显示当前会话的 token 预估。我在动手前会看一眼这个数，超了就手动精简引用文件。实测下来，上下文越干净，模型给出的方案越聚焦；上下文一臃肿，它就开始泛泛而谈。
3.2 项目级规则与索引文件
OpenCode 支持在项目根目录放一个规则文件，它会自动加入每次请求。很多人只把它当注释写几句，但我建议写成可检索的清单格式。规则里每条尽量独立，不要写成长段落。比如"数据库操作统一走 repository 层""禁止在控制器里写业务逻辑"这种，模型能直接执行。
除了规则文件，我还会维护一份简短的架构索引文件，内容是 FAQ 格式：这个项目的主要模块有哪些？关键数据流是怎样的？部署入口在哪儿？因为模型读代码是"从细节反推全貌"的，给一份索引能大幅降低它的理解成本。用 OpenCode 的 include 配置把这份索引固定拼接进去，比让模型自己翻目录高效得多。
还有一个细节是 token 占比验证：规则文件写太长也会占掉上下文预算。我两周前把规则文件精简到 800 token 以内，项目相关的核心约束还都在，但会话可用空间明显变大了。规则文件不是越长越好，要的是精准。
4. 工具调用与自动化：放权与控权的平衡
OpenCode 跟普通聊天式 AI 最大的区别是它能动手干活：读写文件、执行命令、跑测试、查日志。高级配置的核心就是在"放权"和"控权"之间找到平衡。放得太多，模型可能执行危险命令；控得太死，每个操作都要确认，效率反而变成手动操作。
我的配置策略是先缩后放。刚接手一个新项目时，只给读文件和一个限定目录内的命令执行权限，跑上一两天，看模型在这个代码库里的行为是否稳定，再逐步放开写权限。OpenCode 的 allowlist / denylist 配置就是干这个的，它比一刀切权限精细得多。
举个例子，我会在 allowlist 里放 read、write、execute，在 denylist 里放 execute 下的 rm 和 git push。这样模型可以自由地读文件、改文件、跑测试，但不能删文件或推代码。凡是涉及高危操作的，我用 confirm_required 配置让它每次都必须问我，而不是静默执行。
4.1 命令执行的边界配置
命令执行是收益和风险都最大的能力。我先设了 timeout 参数，限制单条命令最长运行时间，默认 120 秒，我把跑测试的会话设成 300 秒，因为测试可能很慢，但我也会设成 60 秒让模型失败后自己思考再换招。关键命令比如杀死进程、重定向输出到系统目录之类，开头的确应该拦一下。
我还会指定 execution.working_dir，让所有命令都限制在项目目录内运行，避免模型跑到用户目录甚至更上层去乱动文件。这对项目隔离很有效，尤其是同时开多个 OpenCode 实例操作不同项目时，不设这个很可能会互相干扰。
4.2 启用联系人和安全策略有效的失效恢复机制
配置命令执行时一定要留好"逃生舱"。OpenCode 支持会话回滚，允许你在模型执行完一系列动作后一键恢复到执行前状态。这个功能在大规模重构场景下太重要了，我至少有三四次是让模型自动改了一批文件，review 时发现方向错了，直接回滚重新来，省掉手动反改的时间。
注意回滚不是万能的。如果模型改完文件后触发外部通知或生成外部请求，这类副作用是回不去的。所以我说放权要渐进，第一次让模型执行带副作用的命令前，先做一次副作用极小的演练，比如打印命令内容或跑一遍简单测试，确认它理解指令意图再放开。
4.3 把自定义工作流做成可复用配置
我建议把项目的常见流程固化成命令，这样不用每次重复描述。OpenCode 在这方面挺好用，你可以在配置里定义一个固定工作流，一键触发。比如"跑全部测试并总结失败用例"，模型会自动去执行 pytest、收集输出、定位失败测试、挨个给出修复建议。
工作流配置的好处是行为可预期。我给我手头某模块配了三个常用流程：构建检查、单测回归、代码规范校验。每个流程的执行步骤都是预先定义好的，模型不会自由发挥，输出结构也一致，我扫一眼就知道这次改动有没有破坏什么。
5. 性能调优：缓存、并发与日志
配置到这一步，OpenCode 已经能好好干活了。但如果你长时间高频使用，性能问题就会浮出来：每次请求都全量复用旧上下文、并发请求把本地资源打满、日志刷屏导致排查困难。这些都要靠性能相关配置解决。
先说缓存。OpenCode 支持对请求做语义缓存，也就是说，如果新的请求和之前某个请求意思相同，可以直接用旧结果。这个配置要关注的是 TTL 和缓存粒度。代码任务里，完全相同的请求很少，但"改动很小"的请求很常见。TTL 设太长，模型会给你过期的代码；设太短，缓存命中率又太低。我实测下来，普通重构 TTL 设 1800 秒左右比较合适，涉及依赖版本变更时我会主动清掉缓存。
日志配置也值得调一下。默认日志级别在开发期是 debug，信息量大到没法看。上了正式环境我会把日志级别调到 warn，只在出错时打日志。需要追踪某次会话行为时，针对性打开 debug 日志，定位到具体行号后立刻关掉。
5.1 并发与超时参数
OpenCode 支持同时处理多个会话请求，并发数调太高，本地机器会卡，尤其在做长任务时 CPU 和内存都被吃满。我建议根据机器性能来设，普通开发机并发数控制在 4 以内，大内存机器可以到 8。实际体感上，超过 8 之后收益明显下降，反而容易出现响应延迟。
超时参数分两个层面：一是命令执行超时，前面提到过；二是模型请求超时，也就是模型代理接口在指定时间内没返回就报错。这个建议设得宽一些，模型推理耗时长是常态，设 60 秒比较合理。但遇到服务端不稳定时，超时报错会频繁打断，我当时是调大了 timeout 并切到备用模型接口才解决。
5.2 会话历史的裁剪策略
OpenCode 默认会在上下文里保留会话历史，因为它要理解你之前说过什么。但历史太长会挤占上下文空间，还会让模型被旧信息带偏。我在配置里对会话历史做了最大轮数限制，超过一定轮数的早期内容会被裁剪，只保留关键信息。
裁剪策略要小心，全局一致裁剪会把重要的早期上下文剪没了。我的做法是手动干预，当讨论进入一个新阶段时，主动开个新会话，把上一轮的结论作为系统提示词带进去。这样历史干干净净，token 利用也最高效。这条经验真心建议试一试，手动开新会话比让模型自动裁剪靠谱得多。
6. 团队协作环境下的配置管理
OpenCode 的配置不只能自己用，还可以跟团队共享。协作配置的核心原则是：把该统一的统一下发，把该隔离的隔离清楚。项目配置文件纳入代码仓库后，所有人拉下来自动生效，这对团队来说价值巨大。
团队配置里最容易踩的坑是密钥管理。配置文件里一旦出现明文密钥，哪怕只是内部仓库，风险也极高。正确方式是配置里只写环境变量名，具体的值由每个人在自己的环境里设置。CI 环境里也可以从密钥管理服务拉取，不用改配置。
团队共享还涉及模型选择的权衡。我经历过团队里有人用高端模型、有人用低成本模型，结果同一个任务的行为表现不一致，很难协作。后来我在项目配置里统一了默认模型，同时允许个人全局配置覆盖成自己偏好的模型。这样既保证默认路径一致，又不剥夺个人偏好。
6.1 配置版本管理与变更记录
项目配置既然进了版本库，就要按版本管理的规矩来。每次调整配置，最好同步改一下变更说明。比如你改动了自动文件选择规则，加了排除 dist 目录，这个变动会直接影响所有成员的会话行为，不写清楚大家会很懵。
我把配置变更记录放在 .opencode 目录下的变更说明文件里，格式很简单：日期、变更项、影响范围、原因。看上去很普通，但三个月后回查"为什么当时排除了那个目录"时，你会感激当初的记录。另外，配置文件的注释也重要，OpenCode 支持注释语法，尽量把每个数组项说明白，不要写只有自己看得懂的缩写。
6.2 多项目切换时的配置隔离
不同项目的技术栈差异很大，OpenCode 配置不能一套打天下。前端项目需要执行 npm 命令，后端项目需要 conda 环境，数据项目要连数据库，这些差异应该体现在各自的项目配置里，而不是全局配置。
我目前的做法是全局配置只保留最基本的模型和密钥读取方式，其余全部放项目级。项目级的命令白名单、目录限制、上下文规则都是独立的。这样从项目 A 切到项目 B，OpenCode 的行为跟着项目走，不会出现给 Python 项目配了一堆 node 工作流的尴尬。
7. 高频问题排查与调试实录
配置 OpenCode 的过程难免遇到各种问题，我把最常踩的几个坑整理成速查表，下次不用再从头查。
| 现象 | 常见原因 | 解决思路 |
|---|---|---|
| 请求报 404 | base_url 路径不对 | 检查是否缺 /v1 路径，对照服务文档 |
| 响应经常中断 | max_tokens 不匹配 | 提高 max_tokens，添加 stop 序列 |
| 模型找不到文件 | 上下文 exclude 误伤 | 检查 exclude 规则，改用 include 显式指定 |
| 改完文件无法回滚 | 回滚功能依赖执行快照 | 执行重大改动前手动确认快照状态 |
| 团队行为不一致 | 全局配置覆盖项目配置 | 统一在项目配置里声明默认模型 |
| 密钥不生效 | 环境变量未加载 | 新开终端窗口加载环境变量再启动 |
7.1 排查型必杀技：开启 debug 日志
遇到某些诡异的问题，最快的方法是把日志级别调到 debug，完整走一遍触发问题的会话，然后把日志里关键节点筛出来。OpenCode 的 debug 日志会打印每次请求的上下文组成、token 数量、工具调用参数，能很直观看到问题出在哪一层。
举个例子，有次模型明明说要读取数据配置文件，最后却读了一个无关的同名文件。不查日志根本猜不到是上下文 exclude 的 glob 写错了，把目标目录整个排除了，模型只能退而求其次找别的路径。开 debug 日志看到 exclude 匹配到了不该匹配的路径，改了规则立刻就好了。
7.2 需要留意的几个安全习惯
最后提醒一下安全习惯。配置权限时宁可先紧后松，不要一开始就给满。模型执行命令的能力很强，但判断力没有强到可以完全托付。尤其是网络请求相关操作，我是默认拦下来的，只有人工确认才放行。另一个建议是定期清理会话日志，OpenCode 的本地日志可能包含代码片段和路径信息，长时间堆积会有泄露风险，配合日志轮转功能按天保留就好。
我个人使用下来的体会是：高级配置不是一次性设定就一劳永逸，它是个动态迭代过程。项目结构一变化、模型一升级，配置就得回头看一眼。好在这套配置体系允许增量修改，不需要推倒重来。隔两三周花十几分钟把上下文规则和权限清单过一遍，OpenCode 就会一直保持在好用的状态。