企业官网建设流程全解析

用 OpenCode 写代码也有大半年了，从一开始只会打开终端敲opencode硬聊，到后来把opencode.json配得明明白白，中间踩过的坑不少。今天这篇就是专门给新手整理的一份配置指南：这个配置文件到底是什么、每一项该怎么写、配完怎么验证，以及那些你大概率会遇到的报错——比如 error from provider (console): opencode's 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/v1，models 里填你本地拉取的模型名就行。

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，还有几个字段看起来不起眼，实际影响体验：

autoupdate这个字段我要单独拿出来说。OpenCode 迭代很快，有时候一周更新好几个版本。开着自动更新，好处是能第一时间用到新功能；坏处是某天打开发现界面变了，或者某个自建 provider 挂掉，一时半会儿摸不着头脑。我是建议在工作用的机器上把autoupdate设为 false，每隔一两周手动升一次，出问题也好定位。

2.4 自定义 Agent 与 Skill

opencode.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_KEY=sk-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_KEY="sk-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): opencode's free tier can only be used from within opencode

console/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 快速排查速查表

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 讲明白的时候，你才是真的会用它了。