刚装好OpenCode兴冲冲地跑起第一条命令结果终端弹出一行红字error from provider (console): opencodes free tier can only be used from within opencode。很多新手在这一步就卡住了网上翻半天也找不到统一答案最后绕了一圈发现问题基本都出在同一个地方——你没有认真配置过opencode.json。这篇就以opencode.json为核心把配置文件从头到尾讲透。不仅告诉你每个字段怎么填还会解释为什么要这么填、不同配置层级之间的覆盖关系以及我在实际使用中遇到的各种报错和排查思路。适合刚装好OpenCode准备上手的新手也适合从Claude Code、Cursor转过来的老手看完至少能少踩一半的坑。1. 为什么建议新手第一件事先研究opencode.json很多人安装完OpenCode就直接开聊能跑通就觉得配置文件不重要。这种想法在头半小时没问题一旦你想换模型、接本地服务、设置权限、处理报错就一定会碰opencode.json。早研究早省事。1.1 默认状态能跑但跑不顺OpenCode开箱自带一套默认配置也会给新用户一些免费模型的试用额度所以理论上什么都不用配就能用。但能用和好用是两码事。默认配置下你的模型选择、请求来源、行为开关基本都是写死的。遇到下面这些需求你会发现绕不开配置文件想用自己的API Key走官方接口而不是一直依赖内置免费额度避免触发来源限制类的报错想在多个模型提供商之间按场景切换比如日常问答用一个、写代码用另一个团队里多个人协作需要统一的模型参数、代理设置或权限策略想装自定义skill、控制AI可执行的操作范围、管理对话归档位置。这些都不是通过命令行参数能优雅解决的opencode.json就是为这个问题设计的。把配置固化到文件里换电脑、换环境、拉新人入伙时复制一份就能复现同样的环境。1.2 配置的三个层级OpenCode的配置大体上分为全局配置和项目配置两类如果再算上环境变量实际是三层。官方文档里的说法可能比较细我按我的理解简化一下全局配置存放在用户主目录下对这台机器上所有OpenCode项目生效。适合放API Key来源、默认主题、全局模型偏好、代理这类通用设置。项目配置存放在具体项目的.opencode/或项目根目录下跟着代码仓库走。适合放项目专属的模型选择、系统提示词、权限规则。团队协作时这部分最好提交到仓库里统一维护。环境变量通过shell注入运行OpenCode时由进程读取。它的优先级最高适合临时覆盖配置比如临时换个API端点或Key去排查问题。优先级关系是环境变量 项目配置 全局配置。理解这个顺序真的很重要很多人配置不生效就是因为全局配置写了一个值项目配置里又有另一个值环境变量再插一脚最后生效的跟你以为的根本不是同一个。1.3 长在源码里的配置文件别当一次性用品我的经验是把opencode.json当成一份环境清单来维护而不是临时改一下就完事。每换一台新机器先把这个文件放好再装OpenCode整个过程五分钟内就能恢复到顺手的状态。尤其是你配置了多个provider之后这个文件的价值会越来越明显。因为provider、model、API Key的对应关系全靠它串联一旦丢了你要么看着报错发呆要么翻聊天记录找之前的配置草稿非常浪费时间。2. 找到配置文件、看懂结构动手前先做两件保险知道了为什么要配接下来就是动手前的基本功文件在哪、长什么样、怎么改才不会改坏。2.1 配置文件到底放在哪OpenCode在不同操作系统上的全局配置路径略有不同但思路一致都是放在用户目录下的配置文件夹里。Linux/macOS~/.config/opencode/opencode.jsonWindows通常也在用户目录下可能是%USERPROFILE%\.config\opencode\opencode.json具体视安装方式而定项目级配置一般放在项目根目录比如./.opencode/opencode.json或者直接叫opencode.json看你用的版本如果你不确定全局配置路径最快的方式是直接列目录ls -la ~/.config/opencode/找不到就手动建一个mkdir -p ~/.config/opencode touch ~/.config/opencode/opencode.json这一步做好至少保证配置文件是存在的后面无论是手动编辑还是让工具自动生成都有落脚点。2.2 一份最小可用的配置长什么样先看一个最简配置感受一下整体结构{ $schema: https://opencode.ai/config.json, provider: { console: { enabled: true } }, model: console/free }这里我故意写了个比较保守的例子实际使用中你大概率会换成真正的API提供商和相关模型。但注意看它的骨架provider负责定义从哪接模型model负责定义默认用哪个模型。完整的opencode.json通常还包含主题、快捷键、权限、skill路径、MCP服务等模块。不用怕字段多日常维护的核心其实就那几块其它按需添加。2.3 改之前先备份改完必须验证语法配置文件是JSON格式JSON有个特点多一个逗号、少一个引号整个文件就废了。OpenCode读到非法JSON时一般会直接报配置解析错误甚至可能默认重置成什么也不加载的状态排查起来很迷惑。所以我建议每次大改前先备份cp ~/.config/opencode/opencode.json ~/.config/opencode/opencode.json.bak改完用Python自带工具校验语法python3 -m json.tool ~/.config/opencode/opencode.json如果输出正常说明语法没问题如果有报错它会告诉你第几行第几列出了什么错照着改就行。这个习惯成本极低但能帮你省掉大量配置文件没生效的排查时间。3. 核心配置项拆解provider、model与身份认证这节是全文重点。很多人配置opencode.json就是为了这十几个字段但往往只抄了写法不理解含义一换场景就抓瞎。3.1 搞清楚provider和model之间的关系打个比方provider是供应商表示你去哪家店买东西model是具体商品表示你买哪款。同一个provider下面可以有多个model。比如你配置了Anthropic作为provider那么claude系列的不同版本就是它名下的不同model你配置了OpenAI的providergpt系列就归它管。在opencode.json里写法的基本逻辑是{ provider: { anthropic: { apiKey: {env:ANTHROPIC_API_KEY}, model: claude-sonnet-4-5 } } }这样设置之后默认模型就是Anthropic下的对应型号。配置多个provider也同理继续往provider对象里加字段就行。3.2 把API Key放进环境变量永远不要明文写在文件里这是我在配置工具类项目时最坚持的一点API Key千万不要直接写成字符串塞进opencode.json。原因很简单全局配置文件虽然在你自己的电脑上但很可能你会拿它做备份、同步到Git仓库、或者发给同事参考。任何一个环节泄露Key就暴露了。而且多个AI工具共存时Key分散在各自配置文件里轮换时极易漏改。推荐的做法是利用环境变量引用。先在shell里设置Keyexport ANTHROPIC_API_KEYsk-ant-xxxx然后在配置文件里写成{ provider: { anthropic: { apiKey: {env:ANTHROPIC_API_KEY} } } }OpenCode解析配置时会自动把{env:ANTHROPIC_API_KEY}替换成当前环境变量值。这样配置文件里从头到尾不含任何真实密钥即使被传到仓库里也是安全的。如果你不想每次开终端都 export可以把它写进shell的配置文件里比如~/.bashrc、~/.zshrc或者在项目目录建一个.env文件让OpenCode加载。具体支持哪种方式看版本但大原则不变密钥永远不入文件正文。3.3 默认模型和临时切换模型配置里设置了model字段后每次启动OpenCode默认就用这个模型。但实际使用中我经常临时切模型比如用默认模型写代码遇到综合分析类问题想换个更擅长推理的模型。这时候不需要改配置文件直接在交互界面里用命令切换即可。命令行模式下一般是斜杠命令加模型名具体命令名因版本而异。知道这个机制就行核心是理解配置文件提供的是默认值不是唯一值。3.4 热搜里那个典型报错的完整排查思路文章开头提到的报错error from provider (console): opencodes free tier can only be used from within opencode我这边实测下来本质是来源认证失败。OpenCode的免费额度绑定的是官方环境请求发出时服务端会校验来源识别不出来源或来源不在白名单内就会拒绝并把错误消息打回给你。排查思路分三步走确认你是不是在OpenCode官方客户端/CLI环境里发起的请求。如果你是在其它程序里直接调用OpenCode的接口或者通过第三方网关去请求很容易触发这个限制。检查opencode.json里是否真的在provider名单里开了console这个入口。免费额度对应的provider就是console如果你把它停了或者模型名写错请求也会落到不可用的状态。确认版本匹配。OpenCode迭代快新旧版本对免费额度的校验逻辑可能有差异。遇到莫名其妙的报错先升级到最新版本再试。如果你确实想用别的API正常接入就不要依赖免费额度直接在配置里换成自己的provider和Key走正常计费通道反而省心。4. 跑通之后的进阶配置skills、权限与本地模型接入基础配置搞定能正常对话了接下来这些配置才是让OpenCode真正顺手的关键。这部分花的时间不多但收益是全方位的。4.1 skill的安装与配置Skill简单理解就是给OpenCode预装一套专家指令。你把某个领域的背景知识、操作规范、输出格式写进skill里之后让AI处理相关任务时它就会自动带上这套上下文回答质量明显不一样。安装skill的方式通常是命令行操作比如opencode skill install skill-name安装之后skill会被放到用户配置目录下的skills文件夹里。如果你希望某些skill只在特定项目里生效或者想改skill的描述、标签可以在opencode.json里增加对应字段。我自己常用的做法是给每个skill写清楚什么时候该用、什么时候不该用否则AI可能在不合适的场景下强行套用效果反而差。4.2 权限控制让AI能干活但不至于乱来OpenCode这类终端AI工具最大的风险不是它不干活而是它太主动——你说一句帮我修一下这个bug它可能顺手就执行了一堆命令包括删除文件、改写配置。权限配置的意义就在这。你可以在opencode.json里设置某些操作需要每次都人工确认某些操作直接禁止某些操作在指定目录内可以自动放行。我个人的配置习惯是读操作放行AI需要频繁读文件来理解项目写操作项目内的文件修改可以放行但全局路径、系统目录一律确认命令执行删除、安装、网络请求这类一律先问一遍环境变量和密钥的读取默认禁止用到了再临时放开。这样既保证了AI的自主性又不至于让它一脚踩进坑里。4.3 接入Ollama本地模型数据安全和离线场景的选择从热搜词里看到很多人搜连接ollama说明本地模型的诉求确实存在。如果你对数据隐私比较敏感或者网络环境不稳定在opencode.json里接入Ollama是个很务实的方案。配置思路和接云端provider一样区别在于端点和模型名。Ollama默认跑在本机的http://localhost:11434你在provider配置里指向这个地址模型名填Ollama里拉取过的本地模型名称即可。注意具体字段名和格式会因为OpenCode版本不同而略有差别建议以当前版本官方文档的schema为准。核心理解记住一点provider不一定要是云厂商本机服务也可以作为provider接进来。4.4 对话归档和数据安全很多人问opencode归档的对话到哪了其实这类工具的对话记录一般都存在本地目录方便续聊和历史检索。归档的好处是不占云端空间、私密性更好坏处是时间久了会积累大量文件占磁盘空间而且如果你重装系统时忘了备份历史对话就直接没了。我一般会在opencode.json里单独指定归档目录并定期把归档文件纳入备份任务。如果你用的是共享电脑建议把归档目录权限收紧毕竟里面可能包含你没注意的敏感代码片段。5. 配置验证、常见排错清单与我的配置习惯最后一节聊点实际的配置改完怎么确认它生效了遇到问题按什么顺序排查以及我踩过几次坑之后总结出来的一套配置习惯。5.1 按顺序验证配置是否正确每次改完opencode.json我都会按下面的顺序快速验证从上到下哪个环节出问题就停在哪个环节JSON语法校验用python3 -m json.tool过一遍语法错误第一时间暴露配置加载确认重启OpenCode看启动日志里是否出现配置解析成功的信息模型列表检查在交互界面里查看当前可用的模型列表确认新加的provider和model出现了发起一条最小请求直接发送一条很短的测试消息确认模型能正常响应权限与skill验证让AI执行一个低风险的读取操作确认权限规则生效再丢一个跟skill领域相关的问题确认skill被正确加载。这套流程五分钟跑完基本能把配置问题从内到外过一遍。5.2 常见报错与处理对照现象可能原因处理方法报错提示来源受限免费额度只能从特定环境用请求来源未通过校验或provider配置错误确认是否在官方环境内使用换成自己的API Key接入配置改了但完全不生效改了全局配置但项目配置或环境变量优先级更高按环境变量 项目配置 全局配置的顺序逐个排查模型列表里看不到新加的模型provider配置格式有问题或模型名与官方不一致对照官方schema检查字段名和模型名启动时提示JSON解析失败文件里有多余逗号、遗漏引号或用错中文字符用json.tool校验并按提示修复用Ollama接入但连不上本地服务未启动或endpoint写错先确认curl http://localhost:11434能通对话归档找不到存档目录被改过或权限不对在配置里显式指定归档目录并确认可写这张表无法覆盖所有情况但大多数新手问题都出在这几类。真遇到没见过的先看完整报错信息再回看配置基本能找到方向。5.3 我现在的配置习惯踩过几次坑之后我现在新装OpenCode的流程基本固定了先建好全局配置目录放一份最小可用的opencode.json只写$schema、provider和model保证能跑。跑通之后再逐步加权限规则、skill路径、归档目录这些进阶项。每次加一项就验证一项绝不一次性写一大版配置再从头排查。API Key一律走环境变量并且在不同Shell里统一用同一个变量名省得换终端后出现诡异的明明配了Key却报无权限。还有一点是定期去看看官方更新日志。OpenCode这类工具更新频率高配置字段偶尔会调整比如某个provider的写法变了、默认行为改了、原来的字段废弃了。这些变化不会在旧文档里出现追更新日志是最直接的消息来源。6. 一些零零碎碎但很实用的经验这部分本来写不写都行但想想还是放出来都是实操中比较琐碎但很影响体验的细节。配置里的注释问题。JSON标准不支持注释但OpenCode的配置文件有时会兼容带注释的写法具体看版本。我的建议是别依赖注释真有解释需求在配置同一目录下放个README.md说明关键字段比注释可读性好得多也避免某些严格解析器直接报错。中文编码问题。配置文件里如果写了中文提示词或模型描述保存时统一用UTF-8无BOM格式。有些Windows编辑器默认存成GBK或者带BOM的UTF-8解析出来可能乱码或者报错。用VS Code或Vim保存基本没这个问题注意别踩即可。密钥轮换时的联动。如果你在多个工具里用了同一个API Key轮换密钥时记得把所有相关配置文件一起改完再重启。我就吃过亏只换了OpenCode的忘了其它工具还挂着旧Key结果两边状态同步出问题排查半天才发现是这个问题。项目配置和团队协作。如果你的项目是多人共用的建议项目级opencode.json只放与项目强相关的配置比如模型选择、固定的skill列表不要放个人偏好的主题和快捷键。个人偏好放全局配置项目配置保持可共享、可解释不然每次合代码都在解决配置文件冲突非常割裂。最后是学习路径的一点点建议。新手阶段多去官方schema里查字段含义比反复试错效率高很多。配置文件的schema本身就是一个活的文档里面能看到所有支持字段的说明和示例。把schema当字典查遇到未知字段先查再填基本不会错。
OpenCode配置文件opencode.json完全指南：从入门到避坑
刚装好OpenCode兴冲冲地跑起第一条命令结果终端弹出一行红字error from provider (console): opencodes free tier can only be used from within opencode。很多新手在这一步就卡住了网上翻半天也找不到统一答案最后绕了一圈发现问题基本都出在同一个地方——你没有认真配置过opencode.json。这篇就以opencode.json为核心把配置文件从头到尾讲透。不仅告诉你每个字段怎么填还会解释为什么要这么填、不同配置层级之间的覆盖关系以及我在实际使用中遇到的各种报错和排查思路。适合刚装好OpenCode准备上手的新手也适合从Claude Code、Cursor转过来的老手看完至少能少踩一半的坑。1. 为什么建议新手第一件事先研究opencode.json很多人安装完OpenCode就直接开聊能跑通就觉得配置文件不重要。这种想法在头半小时没问题一旦你想换模型、接本地服务、设置权限、处理报错就一定会碰opencode.json。早研究早省事。1.1 默认状态能跑但跑不顺OpenCode开箱自带一套默认配置也会给新用户一些免费模型的试用额度所以理论上什么都不用配就能用。但能用和好用是两码事。默认配置下你的模型选择、请求来源、行为开关基本都是写死的。遇到下面这些需求你会发现绕不开配置文件想用自己的API Key走官方接口而不是一直依赖内置免费额度避免触发来源限制类的报错想在多个模型提供商之间按场景切换比如日常问答用一个、写代码用另一个团队里多个人协作需要统一的模型参数、代理设置或权限策略想装自定义skill、控制AI可执行的操作范围、管理对话归档位置。这些都不是通过命令行参数能优雅解决的opencode.json就是为这个问题设计的。把配置固化到文件里换电脑、换环境、拉新人入伙时复制一份就能复现同样的环境。1.2 配置的三个层级OpenCode的配置大体上分为全局配置和项目配置两类如果再算上环境变量实际是三层。官方文档里的说法可能比较细我按我的理解简化一下全局配置存放在用户主目录下对这台机器上所有OpenCode项目生效。适合放API Key来源、默认主题、全局模型偏好、代理这类通用设置。项目配置存放在具体项目的.opencode/或项目根目录下跟着代码仓库走。适合放项目专属的模型选择、系统提示词、权限规则。团队协作时这部分最好提交到仓库里统一维护。环境变量通过shell注入运行OpenCode时由进程读取。它的优先级最高适合临时覆盖配置比如临时换个API端点或Key去排查问题。优先级关系是环境变量 项目配置 全局配置。理解这个顺序真的很重要很多人配置不生效就是因为全局配置写了一个值项目配置里又有另一个值环境变量再插一脚最后生效的跟你以为的根本不是同一个。1.3 长在源码里的配置文件别当一次性用品我的经验是把opencode.json当成一份环境清单来维护而不是临时改一下就完事。每换一台新机器先把这个文件放好再装OpenCode整个过程五分钟内就能恢复到顺手的状态。尤其是你配置了多个provider之后这个文件的价值会越来越明显。因为provider、model、API Key的对应关系全靠它串联一旦丢了你要么看着报错发呆要么翻聊天记录找之前的配置草稿非常浪费时间。2. 找到配置文件、看懂结构动手前先做两件保险知道了为什么要配接下来就是动手前的基本功文件在哪、长什么样、怎么改才不会改坏。2.1 配置文件到底放在哪OpenCode在不同操作系统上的全局配置路径略有不同但思路一致都是放在用户目录下的配置文件夹里。Linux/macOS~/.config/opencode/opencode.jsonWindows通常也在用户目录下可能是%USERPROFILE%\.config\opencode\opencode.json具体视安装方式而定项目级配置一般放在项目根目录比如./.opencode/opencode.json或者直接叫opencode.json看你用的版本如果你不确定全局配置路径最快的方式是直接列目录ls -la ~/.config/opencode/找不到就手动建一个mkdir -p ~/.config/opencode touch ~/.config/opencode/opencode.json这一步做好至少保证配置文件是存在的后面无论是手动编辑还是让工具自动生成都有落脚点。2.2 一份最小可用的配置长什么样先看一个最简配置感受一下整体结构{ $schema: https://opencode.ai/config.json, provider: { console: { enabled: true } }, model: console/free }这里我故意写了个比较保守的例子实际使用中你大概率会换成真正的API提供商和相关模型。但注意看它的骨架provider负责定义从哪接模型model负责定义默认用哪个模型。完整的opencode.json通常还包含主题、快捷键、权限、skill路径、MCP服务等模块。不用怕字段多日常维护的核心其实就那几块其它按需添加。2.3 改之前先备份改完必须验证语法配置文件是JSON格式JSON有个特点多一个逗号、少一个引号整个文件就废了。OpenCode读到非法JSON时一般会直接报配置解析错误甚至可能默认重置成什么也不加载的状态排查起来很迷惑。所以我建议每次大改前先备份cp ~/.config/opencode/opencode.json ~/.config/opencode/opencode.json.bak改完用Python自带工具校验语法python3 -m json.tool ~/.config/opencode/opencode.json如果输出正常说明语法没问题如果有报错它会告诉你第几行第几列出了什么错照着改就行。这个习惯成本极低但能帮你省掉大量配置文件没生效的排查时间。3. 核心配置项拆解provider、model与身份认证这节是全文重点。很多人配置opencode.json就是为了这十几个字段但往往只抄了写法不理解含义一换场景就抓瞎。3.1 搞清楚provider和model之间的关系打个比方provider是供应商表示你去哪家店买东西model是具体商品表示你买哪款。同一个provider下面可以有多个model。比如你配置了Anthropic作为provider那么claude系列的不同版本就是它名下的不同model你配置了OpenAI的providergpt系列就归它管。在opencode.json里写法的基本逻辑是{ provider: { anthropic: { apiKey: {env:ANTHROPIC_API_KEY}, model: claude-sonnet-4-5 } } }这样设置之后默认模型就是Anthropic下的对应型号。配置多个provider也同理继续往provider对象里加字段就行。3.2 把API Key放进环境变量永远不要明文写在文件里这是我在配置工具类项目时最坚持的一点API Key千万不要直接写成字符串塞进opencode.json。原因很简单全局配置文件虽然在你自己的电脑上但很可能你会拿它做备份、同步到Git仓库、或者发给同事参考。任何一个环节泄露Key就暴露了。而且多个AI工具共存时Key分散在各自配置文件里轮换时极易漏改。推荐的做法是利用环境变量引用。先在shell里设置Keyexport ANTHROPIC_API_KEYsk-ant-xxxx然后在配置文件里写成{ provider: { anthropic: { apiKey: {env:ANTHROPIC_API_KEY} } } }OpenCode解析配置时会自动把{env:ANTHROPIC_API_KEY}替换成当前环境变量值。这样配置文件里从头到尾不含任何真实密钥即使被传到仓库里也是安全的。如果你不想每次开终端都 export可以把它写进shell的配置文件里比如~/.bashrc、~/.zshrc或者在项目目录建一个.env文件让OpenCode加载。具体支持哪种方式看版本但大原则不变密钥永远不入文件正文。3.3 默认模型和临时切换模型配置里设置了model字段后每次启动OpenCode默认就用这个模型。但实际使用中我经常临时切模型比如用默认模型写代码遇到综合分析类问题想换个更擅长推理的模型。这时候不需要改配置文件直接在交互界面里用命令切换即可。命令行模式下一般是斜杠命令加模型名具体命令名因版本而异。知道这个机制就行核心是理解配置文件提供的是默认值不是唯一值。3.4 热搜里那个典型报错的完整排查思路文章开头提到的报错error from provider (console): opencodes free tier can only be used from within opencode我这边实测下来本质是来源认证失败。OpenCode的免费额度绑定的是官方环境请求发出时服务端会校验来源识别不出来源或来源不在白名单内就会拒绝并把错误消息打回给你。排查思路分三步走确认你是不是在OpenCode官方客户端/CLI环境里发起的请求。如果你是在其它程序里直接调用OpenCode的接口或者通过第三方网关去请求很容易触发这个限制。检查opencode.json里是否真的在provider名单里开了console这个入口。免费额度对应的provider就是console如果你把它停了或者模型名写错请求也会落到不可用的状态。确认版本匹配。OpenCode迭代快新旧版本对免费额度的校验逻辑可能有差异。遇到莫名其妙的报错先升级到最新版本再试。如果你确实想用别的API正常接入就不要依赖免费额度直接在配置里换成自己的provider和Key走正常计费通道反而省心。4. 跑通之后的进阶配置skills、权限与本地模型接入基础配置搞定能正常对话了接下来这些配置才是让OpenCode真正顺手的关键。这部分花的时间不多但收益是全方位的。4.1 skill的安装与配置Skill简单理解就是给OpenCode预装一套专家指令。你把某个领域的背景知识、操作规范、输出格式写进skill里之后让AI处理相关任务时它就会自动带上这套上下文回答质量明显不一样。安装skill的方式通常是命令行操作比如opencode skill install skill-name安装之后skill会被放到用户配置目录下的skills文件夹里。如果你希望某些skill只在特定项目里生效或者想改skill的描述、标签可以在opencode.json里增加对应字段。我自己常用的做法是给每个skill写清楚什么时候该用、什么时候不该用否则AI可能在不合适的场景下强行套用效果反而差。4.2 权限控制让AI能干活但不至于乱来OpenCode这类终端AI工具最大的风险不是它不干活而是它太主动——你说一句帮我修一下这个bug它可能顺手就执行了一堆命令包括删除文件、改写配置。权限配置的意义就在这。你可以在opencode.json里设置某些操作需要每次都人工确认某些操作直接禁止某些操作在指定目录内可以自动放行。我个人的配置习惯是读操作放行AI需要频繁读文件来理解项目写操作项目内的文件修改可以放行但全局路径、系统目录一律确认命令执行删除、安装、网络请求这类一律先问一遍环境变量和密钥的读取默认禁止用到了再临时放开。这样既保证了AI的自主性又不至于让它一脚踩进坑里。4.3 接入Ollama本地模型数据安全和离线场景的选择从热搜词里看到很多人搜连接ollama说明本地模型的诉求确实存在。如果你对数据隐私比较敏感或者网络环境不稳定在opencode.json里接入Ollama是个很务实的方案。配置思路和接云端provider一样区别在于端点和模型名。Ollama默认跑在本机的http://localhost:11434你在provider配置里指向这个地址模型名填Ollama里拉取过的本地模型名称即可。注意具体字段名和格式会因为OpenCode版本不同而略有差别建议以当前版本官方文档的schema为准。核心理解记住一点provider不一定要是云厂商本机服务也可以作为provider接进来。4.4 对话归档和数据安全很多人问opencode归档的对话到哪了其实这类工具的对话记录一般都存在本地目录方便续聊和历史检索。归档的好处是不占云端空间、私密性更好坏处是时间久了会积累大量文件占磁盘空间而且如果你重装系统时忘了备份历史对话就直接没了。我一般会在opencode.json里单独指定归档目录并定期把归档文件纳入备份任务。如果你用的是共享电脑建议把归档目录权限收紧毕竟里面可能包含你没注意的敏感代码片段。5. 配置验证、常见排错清单与我的配置习惯最后一节聊点实际的配置改完怎么确认它生效了遇到问题按什么顺序排查以及我踩过几次坑之后总结出来的一套配置习惯。5.1 按顺序验证配置是否正确每次改完opencode.json我都会按下面的顺序快速验证从上到下哪个环节出问题就停在哪个环节JSON语法校验用python3 -m json.tool过一遍语法错误第一时间暴露配置加载确认重启OpenCode看启动日志里是否出现配置解析成功的信息模型列表检查在交互界面里查看当前可用的模型列表确认新加的provider和model出现了发起一条最小请求直接发送一条很短的测试消息确认模型能正常响应权限与skill验证让AI执行一个低风险的读取操作确认权限规则生效再丢一个跟skill领域相关的问题确认skill被正确加载。这套流程五分钟跑完基本能把配置问题从内到外过一遍。5.2 常见报错与处理对照现象可能原因处理方法报错提示来源受限免费额度只能从特定环境用请求来源未通过校验或provider配置错误确认是否在官方环境内使用换成自己的API Key接入配置改了但完全不生效改了全局配置但项目配置或环境变量优先级更高按环境变量 项目配置 全局配置的顺序逐个排查模型列表里看不到新加的模型provider配置格式有问题或模型名与官方不一致对照官方schema检查字段名和模型名启动时提示JSON解析失败文件里有多余逗号、遗漏引号或用错中文字符用json.tool校验并按提示修复用Ollama接入但连不上本地服务未启动或endpoint写错先确认curl http://localhost:11434能通对话归档找不到存档目录被改过或权限不对在配置里显式指定归档目录并确认可写这张表无法覆盖所有情况但大多数新手问题都出在这几类。真遇到没见过的先看完整报错信息再回看配置基本能找到方向。5.3 我现在的配置习惯踩过几次坑之后我现在新装OpenCode的流程基本固定了先建好全局配置目录放一份最小可用的opencode.json只写$schema、provider和model保证能跑。跑通之后再逐步加权限规则、skill路径、归档目录这些进阶项。每次加一项就验证一项绝不一次性写一大版配置再从头排查。API Key一律走环境变量并且在不同Shell里统一用同一个变量名省得换终端后出现诡异的明明配了Key却报无权限。还有一点是定期去看看官方更新日志。OpenCode这类工具更新频率高配置字段偶尔会调整比如某个provider的写法变了、默认行为改了、原来的字段废弃了。这些变化不会在旧文档里出现追更新日志是最直接的消息来源。6. 一些零零碎碎但很实用的经验这部分本来写不写都行但想想还是放出来都是实操中比较琐碎但很影响体验的细节。配置里的注释问题。JSON标准不支持注释但OpenCode的配置文件有时会兼容带注释的写法具体看版本。我的建议是别依赖注释真有解释需求在配置同一目录下放个README.md说明关键字段比注释可读性好得多也避免某些严格解析器直接报错。中文编码问题。配置文件里如果写了中文提示词或模型描述保存时统一用UTF-8无BOM格式。有些Windows编辑器默认存成GBK或者带BOM的UTF-8解析出来可能乱码或者报错。用VS Code或Vim保存基本没这个问题注意别踩即可。密钥轮换时的联动。如果你在多个工具里用了同一个API Key轮换密钥时记得把所有相关配置文件一起改完再重启。我就吃过亏只换了OpenCode的忘了其它工具还挂着旧Key结果两边状态同步出问题排查半天才发现是这个问题。项目配置和团队协作。如果你的项目是多人共用的建议项目级opencode.json只放与项目强相关的配置比如模型选择、固定的skill列表不要放个人偏好的主题和快捷键。个人偏好放全局配置项目配置保持可共享、可解释不然每次合代码都在解决配置文件冲突非常割裂。最后是学习路径的一点点建议。新手阶段多去官方schema里查字段含义比反复试错效率高很多。配置文件的schema本身就是一个活的文档里面能看到所有支持字段的说明和示例。把schema当字典查遇到未知字段先查再填基本不会错。