用 OpenCode 写代码也有大半年了从一开始只会打开终端敲opencode硬聊到后来把opencode.json配得明明白白中间踩过的坑不少。今天这篇就是专门给新手整理的一份配置指南这个配置文件到底是什么、每一项该怎么写、配完怎么验证以及那些你大概率会遇到的报错——比如 error from provider (console): opencodes free tier can only be used from within opencode。先说清楚服务对象OpenCode 是终端里跑的一个开源 AI 编程助手可以把它理解成 Claude Code 的开源平替也支持多模型、多服务商、MCP 工具、自定义 Agent。只要你想在公司项目里稳定用它或者想在本地接一套自己常用的模型opencode.json都是绕不开的一环。1. 先搞清楚 opencode.json 是什么1.1 它到底管什么opencode.json 是 OpenCode 的配置文件作用范围以项目为单位。你可以把它放在项目根目录也可以放到用户全局目录让所有项目共享同一份基础设置。这个文件控制的东西很多但核心就这几类模型从哪里来provider、默认用哪个模型model、AI 能不能执行危险操作permission、要挂哪些外部工具mcp、要不要加载自定义工作流agent / skill。有一个很多新手会忽略的点OpenCode 支持opencode.json和opencode.jsonc两种写法。前者是标准 JSON不能写注释后者允许注释和尾逗号适合在团队里当“带说明的配置”来维护。如果你只想给自己用直接建opencode.json就行一旦配置多了强烈建议换成.jsonc后缀。1.2 配置文件的加载顺序全局配置和项目配置不会互相抵消而是做深度合并。也就是说你在全局配了一个默认模型在项目里只想改权限那只要在项目配置里写permission就够了模型仍然沿用全局的。加载优先级大概是这样的命令行参数 项目配置 全局配置 内置默认值。实际排查问题的时候这个顺序非常关键。很多“我明明改了不生效”的案例最后都是因为全局配置里写了同样的字段项目配置没盖住或者反过来。1.3 最小可用配置长什么样新手别一上来就背一堆字段先跑通一个最小配置{ $schema: https://opencode.ai/config.json, model: console/free, theme: opencode, autoupdate: true }把这段保存成opencode.json放到项目根目录然后执行opencode。如果能看到 AI 正常回复说明配置文件已经生效了。console/free是 OpenCode 自带的免费档位用它先验证链路最稳妥后面再换成你自己的模型。2. 配置文件核心字段逐个拆解2.1 provider 与 model先让模型真正跑起来provider 是 OpenCode 里“模型服务商”的概念。OpenCode 自带了 Anthropic、OpenAI、Google、Console 等常见服务商登录官方账号就能用。但自带的永远不够尤其是平时要接国产模型或者本地模型的场景最常干的其实就是两件事接远程模型、接本地模型。接远程模型或自建模型服务核心是写一个自定义 provider。下面是一个对接 DeepSeek 的例子{ provider: { deepseek: { npm: ai-sdk/openai-compatible, name: DeepSeek, options: { baseURL: https://api.deepseek.com/v1, apiKey: {env:DEEPSEEK_API_KEY} }, models: { deepseek-chat: { name: DeepSeek V3 }, deepseek-reasoner: { name: DeepSeek R1 } } } }, model: deepseek/deepseek-chat }{env:DEEPSEEK_API_KEY}是 OpenCode 支持的环境变量引用写法等于告诉它“去环境变量里找这个值”避免把密钥直接写进配置文件。接 Ollama 本地模型也是同样的套路把 baseURL 改成http://localhost:11434/v1models 里填你本地拉取的模型名就行。model和small_model要分清。model是主对话模型承担主要推理small_model是轻量任务模型比如给对话生成标题、做按钮提示这类跑量但不需要大模型的小事。你可以用便宜的小模型干杂活把贵的留给人话多的主对话。还有一种情况你在配置里写了模型 ID但运行时提示找不到。别急着怀疑 OpenCode先打开/models看看真实的模型 ID 列表。很多自定义 provider 的模型 ID 要和接口返回的完全一致差一个短横线都连不上。2.2 permission控制 AI 的“手脚”AI 编程助手最怕的不是它不够聪明而是它太勤快。OpenCode 的 permission 字段就是用来限制 AI 能调用哪些工具、要不要经过你确认。{ permission: { defaultMode: ask, allow: [read, glob, grep], ask: [write, edit, bash], deny: [webfetch] } }defaultMode决定没列出来的工具走什么策略allow 放行、ask 每次询问、deny 直接禁止。上面这个配置的意思是读取文件、搜索这类只读操作放行写文件、编辑、执行 bash 命令要问你一句联网抓网页直接禁止。我的建议是新手前三周别把defaultMode设成 allow。亲眼看过 AI 把自己刚写的代码删掉重写、然后越写越坏之后你就会珍惜每一次ask弹窗了。等你对某个项目的文件结构足够熟、也有完整 git 兜底了再考虑放开写权限。2.3 其他实用字段别忽略除了 provider 和 permission还有几个字段看起来不起眼实际影响体验字段作用示例theme终端界面主题opencode、catppuccinautoupdate是否自动更新 OpenCodetrue / falseexperimental开启实验性功能true / falseformat输出格式相关配置默认即可不建议动notifications是否发送系统通知true / falseautoupdate这个字段我要单独拿出来说。OpenCode 迭代很快有时候一周更新好几个版本。开着自动更新好处是能第一时间用到新功能坏处是某天打开发现界面变了或者某个自建 provider 挂掉一时半会儿摸不着头脑。我是建议在工作用的机器上把autoupdate设为 false每隔一两周手动升一次出问题也好定位。2.4 自定义 Agent 与 Skillopencode.json 里还能定义自定义 Agent。简单理解Agent 就是一个带固定人设和固定工具的“角色”。比如我想让 AI 在提交前专门做 code review可以这样配{ agent: { review: { description: 专门做代码审查的 agent, prompt: 你是一名严格的高级工程师发现潜在 bug、安全和性能问题时要明确指出来。, model: deepseek/deepseek-chat } } }配置好之后在 OpenCode 里输入/review就能切到这个角色。这个能力在团队协作时特别有用——有人负责写功能、有人负责审查用不同的 agent 把上下文隔离开比共享一个大模型上下文干净得多。Skill 是 OpenCode 近一版重点推的能力。你可以把团队里反复用到的工作流比如“修 bug 前先看日志、再定位、再改代码”这一步一步沉淀成SKILL.md文件放到项目的.opencode/skill目录下。OpenCode 会自动识别AI 在需要时就会参考这个技能文件。配置文件里也有skills相关字段可以管理启停适合按项目切换不同技能包。3. 从零到一完整配置实操3.1 安装与初始化如果你还没装 OpenCode最省事的方式是执行官方安装脚本curl -fsSL https://opencode.ai/install | bash或者你已经装了 Node.js也可以用 npm 全局安装npm install -g opencode-ai装完先别急着配文件直接跑一次opencode完成初始化。第一次运行会引导你登录服务商可以用官方账号也可以跳过。这一步的主要目的是确认二进制没问题同时让 OpenCode 生成默认的全局配置目录。3.2 创建项目配置文件初始化完成后在项目根目录创建opencode.json先写最小配置。这里有个小技巧如果你不确定字段名先建文件再运行opencode等报错。OpenCode 对配置的报错信息很明确会直接告诉你哪一行、哪个字段不认识。我建议的落地顺序是先只写 model跑通再加 provider跑通再动 permission最后加 mcp。一次只改一个变量出了问题可以一眼定位。3.3 接入真实模型以 Anthropic 为例先在终端里设置环境变量export ANTHROPIC_API_KEYsk-ant-xxxx然后在opencode.json里这样引用{ provider: { anthropic: { npm: ai-sdk/anthropic, options: { apiKey: {env:ANTHROPIC_API_KEY} }, models: { claude-sonnet-4: { name: Claude Sonnet 4 } } } }, model: anthropic/claude-sonnet-4 }需要注意{env:ANTHROPIC_API_KEY}的取值发生在 OpenCode 启动时。如果你在另一个终端窗口 export 了变量当前窗口里的 OpenCode 是读不到的得重启或者重新 export。另一个坑是很多服务商的密钥在终端里带特殊字符导致 export 被截断建议把密钥用引号包起来写export ANTHROPIC_API_KEYsk-ant-xxxx。3.4 配置 MCP 服务器MCP 可以把外部工具接进 AI 对话。你可以把它想成“给 AI 插 U 盘”默认的 AI 只有一张嘴和一个记事本挂上 MCP 之后它能读取本地文件系统、操作浏览器、查数据库。在 opencode.json 里加一段 mcp 配置{ mcp: { filesystem: { type: local, command: [npx, -y, modelcontextprotocol/server-filesystem, .], enabled: true } } }这个例子是让 AI 可以读写当前目录下的文件。command必须是数组不要把整条命令写成字符串否则会报类型错误。如果 MCP 服务需要环境变量用environment字段传不要塞进 command 里。初次配 MCP 最容易踩的坑是npx需要联网下载某些内网环境会卡住。如果下载超时可以先手动执行一次命令把依赖装好再启动 OpenCode。3.5 验证配置是否生效配置写完之后在 OpenCode 里用斜杠命令检查。/status能看当前主模型、小模型、权限模式/models能列出所有可用模型并标明哪个是默认/mcp能看 MCP 服务器状态。这些命令在你怀疑“配置到底起没起作用”时最有用。验证配置的最快方式是随便问 AI 一句“你当前用的是什么模型”。它会从自己的上下文里读出模型 ID如果和配置里写的对得上说明链路通了如果还是旧模型大概率是全局配置覆盖了项目配置回~/.config/opencode/opencode.json检查一遍就明白了。4. 新手最容易踩的坑与排查技巧4.1 遇到 free tier 报错怎么办这个报错出现频率特别高值得单独讲error from provider (console): opencodes free tier can only be used from within opencodeconsole/free是 OpenCode 官方提供给自家终端工具使用的免费额度。它有一个限制只能在 OpenCode 本体里使用。如果你把模型切到console/free然后又通过 cc-switch、Claude Code 这类外部客户端去连接 OpenCode或者自己写脚本走接口去调用它服务端就会做客户端校验发现请求不是从 OpenCode 发出来的直接拒绝并抛出这行报错。这不是网络问题也不是密钥问题纯粹是“免费餐只能堂食”。想解决要么回到 OpenCode 里用要么配置一个有 API Key 的真实模型比如 Anthropic、OpenAI、DeepSeek、Ollama让外部客户端走这些 provider。特别提醒如果你搜方案时看到有人说“加个客户端标识就能绕过”千万别信这种校验不是靠配置能绕过的老老实实换模型更省时间。4.2 配置不生效的几类原因我遇到的“配置不生效”案例90% 出在这几个地方。一是文件路径不对。项目配置必须叫opencode.json大小写别错全局配置必须在~/.config/opencode/目录下。二是 JSON 格式错误。手写配置最容易出尾逗号比如model: xxx,后面还跟着一个逗号标准 JSON 直接报错。三是字段拼写问题比如把permission写成permissions就不认了。四是扩展名混淆开了.jsonc就用.json的严格规则写注释导致解析失败。排查顺序建议是先看终端有没有报错再看文件路径最后把配置里的字段逐个删掉二分定位。别小看二分法在配置文件越来越长之后它就是最快的排障方式。4.3 API Key 与环境变量的坑另一个高频问题模型连不上报 401 或者 invalid api key。大多数时候不是密钥错了而是 OpenCode 没读到。比如你把ANTHROPIC_API_KEY写进了 shell 的 rc 文件但在图形界面环境或者 IDE 的终端里启动 OpenCode环境变量可能就没被加载。再比如你改了.env文件但 OpenCode 不会自动重新读取必须重启进程。更隐蔽的是有些服务商的 SDK 会优先读自己的环境变量名比如 Anthropic 官方 SDK 认的是ANTHROPIC_API_KEY但你在配置里用的是ANTHROPIC_AUTH_TOKEN两者不一致也会失败。我的做法是所有密钥统一用{env:XXX}引用并且在实际启动前先echo $XXX确认值能打出来。打不出来说明环境变量根本没进到当前进程后面所有排查都白搭。4.4 快速排查速查表症状可能原因处理方式启动报 JSON 解析错误尾逗号、注释、多余空格改用 .jsonc 或删掉注释model 找不到模型 ID 不对/models 查看真实 ID401 / invalid key环境变量没读到echo 验证变量重启 OpenCodefree tier 报错在外部客户端用 console/free换真实模型 providerMCP 连接失败npx 首次下载超时手动预下载检查环境变量改了配置没变化全局配置覆盖项目配置检查两级配置合并结果5. 一份可以直接抄的配置模板5.1 完整模板与逐段说明下面是一份带注释的opencode.jsonc覆盖了日常开发 90% 的场景直接复制改成你的密钥就能用{ $schema: https://opencode.ai/config.json, // 主模型按需改成你的服务商/模型 model: anthropic/claude-sonnet-4, // 小模型跑标题生成/摘要等轻量任务 small_model: anthropic/claude-haiku-4, theme: opencode, autoupdate: false, // 自定义 provider国产/自建模型都在这加 provider: { deepseek: { npm: ai-sdk/openai-compatible, name: DeepSeek, options: { baseURL: https://api.deepseek.com/v1, apiKey: {env:DEEPSEEK_API_KEY} }, models: { deepseek-chat: { name: DeepSeek V3 } } } }, // 权限只读放行写和执行要确认 permission: { defaultMode: ask, allow: [read, glob, grep], ask: [write, edit, bash], deny: [] }, // MCP 工具按需挂载 mcp: { filesystem: { type: local, command: [npx, -y, modelcontextprotocol/server-filesystem, .], enabled: true } }, // 自定义 agent agent: { review: { description: 代码审查角色, prompt: 你是资深代码审查员重点关注安全性和可维护性。 } } }这份模板的定位是“安全优先”AI 可以自由读代码但每次写文件、跑命令都要经过你确认。你可以根据项目风险调permission比如在测试项目里把bash也放行效率会明显提升但前提是你有完整的 git 保护和随时回滚的心理准备。5.2 团队协作时的建议如果这份配置要入库和团队共享我建议把密钥全部改成{env:XXX}形式绝不出现明文。同时把.env之类持有真实密钥的文件加进.gitignore。团队里每个人用自己的密钥配置文件保持一致新成员 clone 下来就能跑。另外OpenCode 的历史会话默认存在本机数据目录macOS/Linux 通常在~/.local/share/opencode下。如果归档对话找不到了先去这个目录翻按项目名和时间戳找对应的 session 文件。团队如果要共享会话记录目前最靠谱的方式还是定期导出或者借助自建的 MCP 工具写入团队知识库。5.3 后续还能怎么玩opencode.json 只是一个入口真正值钱的是围绕它长出来的生态。Skill 可以把团队工作流固化插件能改终端交互行为MCP 能把 AI 接进内部系统自定义 provider 能让你用上任何兼容 OpenAI 的模型服务。官方目前也有面向大用量场景的付费套餐比如 go 套餐配置方式和普通模型完全一样只是用量额度不同。玩法几乎没有上限但有一条原则值得记住配置永远是服务效率的不是用来堆砌的。每加一个字段之前先问自己——这能让我现在的工作少花一分钟吗如果答案模棱两可就别加。最后再分享我自己的一个体会。我刚接触 opencode.json 时总想着把所有字段一次性写完结果要么是模型 ID 写错连不上要么是权限放太开AI 趁我不注意自己改了一堆文件我就在那里一遍遍看 git diff。后来我彻底学乖所有新配置都从最小集开始加每次只加一个改动跑通了再动下一个。这个方法很土但真的能让你把每一行配置的后果都搞清楚。别看网上各种“高级配置”满天飞等你能把一个最小的 opencode.json 讲明白的时候你才是真的会用它了。