企业官网建设流程全解析

如果你用过 OpenCode，大概率对它的默认模型体验有清晰感知：开箱即用很爽，但真要把它换成自己团队部署的模型，或者接入本地推理服务时，一堆配置问题就冒出来了。OpenCode 自定义模型配置看起来只是填几个字段，实际涉及服务地址、鉴权方式、模型名称、上下文长度、超时策略等多个环节，任何一个对不上都会让补全直接罢工。这篇内容我按自己的实操经验整理出来，适合所有想把 OpenCode 接到自定义模型上的开发者，不管你是个人折腾，还是团队要做统一接入，都可以照着走一遍。

1. 为什么要折腾自定义模型配置

1.1 默认模型的“够用”与“不够用”

OpenCode 装好之后默认连的是公共模型服务，大多数时候确实“够用”：补全、解释代码、生成注释，这些常规操作基本没毛病。但我在实际项目里发现，默认模型的“够用”是有边界的，而且这个边界来得比想象中快。

边界主要体现在几个方面。第一是数据敏感，公司内部项目的代码片段会通过公共模型服务走一圈，很多团队根本接受不了这个前提。第二是成本，公共模型按 token 计费，个人折腾还好，团队高频使用一个月下来账单相当可观。第三是可控性，默认模型的参数、版本、服务状态都不是你能决定的，服务端一升级，行为可能就变了。第四才是模型能力本身，通用模型在特定技术栈、特定内部规范上的表现，往往不如你针对场景调过的模型。

所以我一直觉得，自定义模型配置不是“进阶玩法”，而是“必学技能”。你不需要每天换模型，但你至少得知道怎么换，以及换了之后怎么排错。

1.2 自定义模型能解决的三类问题

自定义模型配置，本质上做的一件事：把 OpenCode 的“模型来源”从固定服务，改成你指定的任意服务。听起来简单，但它能解决的问题很实在。

第一类是隐私与合规问题。把模型服务切到内网自建的推理服务，代码只在公司内部流转，从源头切断数据外送。这对很多研发团队来说是硬需求，不是可选项。

第二类是成本问题。内部部署的模型无论是按调用计费还是按资源占用计费，单价通常都比公共模型低。如果只是做代码补全和解释，长期用下来差距非常明显。

第三类是模型自由度问题。你可以接微调过的内部模型，也可以按任务切换不同模型，比如简单补全用轻量模型，复杂重构用大参数模型。这种灵活性，是默认模型给不了的。

用一个不太严谨但很贴切的类比：默认模型像公司食堂的固定套餐，能吃饱但天天一样；自定义模型就像你自己开小灶，食材、口味、分量都能自己定，代价是你得自己下厨。

1.3 适用人群与场景

我接触过的使用场景大致有三类，你可以对号入座。

第一类是个人开发者。自己在本地跑一个推理服务，把 OpenCode 接上去，折腾成本不高，还能完全掌控数据。第二类是小型技术团队。团队内部搭一个共享的模型网关，配置一次，所有人统一接入，既省钱又方便管理。第三类是数据敏感型企业。业务代码不能出内网，只能用内网模型服务，自定义配置就是唯一选项。

如果你完全不想折腾，只想要“装上就能用”，那默认模型确实更省心。自定义模型配置适合那些愿意花一小时排查问题、换取长期可控性的开发者。这篇文章后面的内容，我也会默认你有这个心理准备。

2. 开工前的准备：版本、服务与信息

2.1 确认 OpenCode 版本与配置入口

很多人在配置自定义模型时犯的第一个错，就是拿着网上老教程的配置路径直接套。OpenCode 不同版本的配置文件路径、字段命名、优先级规则都有差异，所以第一步必须是确认你自己的版本。

命令行里执行opencode --version，先看版本号。然后再看配置入口，一般常见的有三种：用户级配置、项目级配置、环境变量。用户级配置通常在当前用户的配置目录下，比如~/.config/opencode/下的 JSON 文件；项目级配置一般在项目根目录的.opencode.json或opencode.json里；环境变量则是以OPENCODE_开头的一组变量。

我的习惯是先执行opencode config list看当前生效的配置路径，再决定改哪个文件。很多“改了没生效”的问题，其实都是改错了文件。默认配置可能有多个加载层级，项目级会覆盖用户级，环境变量又会覆盖文件里的值，所以一旦没生效，先想想是不是被更高优先级的配置盖住了。

2.2 准备模型服务：云端 API 与本地部署

自定义模型配置的“模型服务”来源，大致分两条路线：远程 API 和本地部署。

远程 API 一般是团队内部的模型网关，或者某个模型服务商提供的标准接口。你只需要拿到一个服务地址和对应的 Key。这类服务的优点是部署零成本、算力充足，缺点是数据要经过网络传输，且依赖外部服务的稳定性。

本地部署则是在你自己的机器或内网服务器上跑一个推理框架，加载开源模型，监听某个端口。这种方式数据完全可控，响应延迟也可能更低，但你需要自己处理模型下载、显存占用、服务并发这些问题。

两条路线在 OpenCode 里的配置逻辑完全一样，区别只是服务地址指向哪里。远程 API 就填网关地址，本地部署就填http://127.0.0.1:8080这类内网地址。我建议新手先从本地部署开始，因为环境可控，出了问题也好排查，不用怀疑是不是网络链路的问题。

2.3 需要收集的关键信息清单

动手改配置之前，先把下面这些信息收集齐，可以省掉大量试错时间。

• 服务地址，也就是模型服务的 base URL，比如内网地址或者本地端口。
• API Key，如果有鉴权的话。注意有些本地服务不校验 Key，但也建议先填一个占位符。
• 模型名称，这是最容易出错的项，必须精确匹配服务端模型列表里的名称。
• 接口格式，确认你的模型服务使用什么风格的对话接口，OpenCode 通常支持标准对话补全接口。
• 上下文长度，模型最大支持多少 token，决定你的 maxTokens 和请求内容不能超限。
• 限流与并发限制，避免高频率请求把服务打挂。

尤其是“模型名称”这一项，很多人习惯凭印象填一个形似的名字，结果服务端返回 404。正确做法是先通过服务端提供的模型列表接口，把服务上真实存在的模型名拉出来，再复制粘贴到配置里。这一步做扎实，后面至少能避开一半的报错。

3. 核心配置项逐个拆解

3.1 配置文件的加载逻辑

OpenCode 的配置加载逻辑，和大多数现代开发工具类似，遵循“优先级由高到低”的规则：命令行参数高于环境变量，环境变量高于项目级配置，项目级配置高于用户级配置，用户级配置再覆盖内置默认值。

这个设计很合理，它让你既能在全局设一套“兜底配置”，又允许每个项目单独覆盖。比如我在用户级配置里默认指向本地模型服务，但在某个涉及复杂重构的项目里，通过项目级配置临时切换到参数更强的模型。

理解这个逻辑之后，配置不生效的时候你就知道往哪查：先在命令行里看实际生效的配置，再倒推是哪一层覆盖了你的设置。不要一上来就怀疑配置文件写错了。

JSON 配置文件有个硬性要求：不能写注释，不能有尾逗号。很多编辑器对 JSON 的宽容度很高，但 OpenCode 的解析器不一定宽容。我推荐填完配置后用格式化工具跑一遍，语法错误早发现早解决。

3.2 一个最小可用的配置样例

先给你一个可以直接抄的最小配置，假设你在本地跑了一个模型服务，监听 8080 端口：

{ "model": { "provider": "custom", "baseUrl": "http://127.0.0.1:8080", "apiKey": "sk-local-key", "model": "my-model-name" } }

这个配置做了四件事：声明使用自定义模型服务，指定服务地址，带上鉴权 Key，告诉客户端模型叫什么。

这里有两个容易忽略的细节。第一，baseUrl最后不要带斜杠，带了可能导致请求路径拼接错误。第二，如果本地服务不校验 Key，也不要留空，填一个占位符如sk-local-key，避免客户端的鉴权逻辑被跳过导致行为不一致。

把这份配置存到项目根目录的opencode.json，重启 OpenCode，然后在对话框里随便输入一段代码，如果能看到补全结果，说明最小链路已经通了。接下来再谈微调。

3.3 核心参数详解与推荐值

最小配置只能保证“跑通”，要想“好用”，还得理解下面这些参数。

为什么代码补全的temperature要调低？因为代码补全本质上是“确定性问题”，你希望模型给出的答案是稳定、可预期的。温度一高，模型就放飞自我，同样的输入可能每次补全结果都不一样，这在 IDE 里是灾难。反过来，如果你用 OpenCode 做头脑风暴式的对话，温度可以适当提高。

maxTokens也要留意。设得太短，长代码补全到一半就断了；设得太长，又可能超过模型上下文上限。一个稳妥的做法是，先查清楚模型的最大上下文窗口，把maxTokens设为窗口的四分之一到三分之一，给输入内容留足空间。

3.4 多模型并存与切换

实际使用中，单一模型很难满足所有场景。我在日常开发时，会把多个模型一起配好，然后按任务切换。

配置结构大致是这样：

{ "providers": { "local-fast": { "baseUrl": "http://127.0.0.1:8080", "apiKey": "sk-local-key", "model": "fast-model" }, "team-powerful": { "baseUrl": "http://team-gateway.internal", "apiKey": "sk-team-key", "model": "powerful-model" } } }

日常简单补全用local-fast，轻量、快速、省资源；遇到复杂重构、跨文件分析时切到team-powerful，让它处理更重的问题。

切换动作一般在 OpenCode 的模型选择入口完成，不需要反复改配置文件。多模型并存的另一个好处是：一个模型服务挂了，你可以一键切到备用模型，不至于完全卡死。我把这个习惯称为“给自己留后路”，在后面的进阶章节会展开讲。

4. 实操全流程：从配置到跑通

4.1 第一步：确认服务地址可访问

千万不要一上来就改 OpenCode 配置，先用命令行单独验证模型服务是否可用。这一步能帮你把“模型服务的问题”和“OpenCode 配置的问题”彻底分开。

我一般用 curl 拉一下模型列表：

curl http://127.0.0.1:8080/v1/models \ -H "Authorization: Bearer sk-local-key"

如果返回一个 JSON 数组，里面列出了模型 ID，说明服务地址和 Key 都没问题。如果连接被拒绝，先检查服务进程是否在运行、端口是否正确、防火墙是否拦截了本机访问。如果返回 401 或 403，说明 Key 不对或者鉴权方式需要调整。

这一步花不了两分钟，但能省掉后面的大量时间。我最开始配置时，服务端口少写了个数字，OpenCode 反复报超时，我一直在配置里找原因，最后才想起来用 curl 验证地址，一查就发现是端口错了。

4.2 第二步：写好配置文件

确认服务可用之后，开始写 OpenCode 配置。我通常会在项目根目录放一个opencode.json，方便团队统一。一个更完整、适合日常使用的配置版本如下：

{ "model": { "provider": "custom", "baseUrl": "http://127.0.0.1:8080", "apiKey": "sk-local-key", "model": "my-model-name", "temperature": 0.2, "maxTokens": 2048, "timeout": 120, "stream": true } }

注意几个细节。timeout设成 120 秒，是因为本地模型首次请求可能需要加载模型，响应时间会明显偏长，严格的 60 秒超时会让请求在模型还没完全加载时就中断。stream开启后，openCode 可以边生成边显示，体验上比等待完整响应要顺畅得多。

保存文件之前，再确认一次 JSON 格式没有语法错误。我习惯用命令行里的 JSON 解析工具做校验，而不是只靠肉眼。校验通过后再重启 OpenCode，让配置重新加载。

4.3 第三步：设置环境变量

如果不想把 API Key 直接写进配置文件，可以用环境变量来覆盖敏感字段。这种方式在团队共享配置时尤其重要，因为配置文件会进入版本库，而 Key 属于秘密信息。

Linux 或 macOS 下可以直接在 shell 里设置：

export OPENCODE_MODEL_BASE_URL="http://127.0.0.1:8080" export OPENCODE_MODEL_API_KEY="sk-local-key"

Windows 下则是：

set OPENCODE_MODEL_BASE_URL="http://127.0.0.1:8080" set OPENCODE_MODEL_API_KEY="sk-local-key"

设置之后，配置文件里可以留空或者不写 Key，OpenCode 会优先读取环境变量。我个人的习惯是：配置文件里保存所有非敏感字段，敏感字段全部走环境变量。这样即便配置文件被提交到代码仓库，也不会泄露密钥。

环境变量的具体名字可能因 OpenCode 版本而异，建议先查当前版本的文档或执行opencode config list确认变量名。

4.4 第四步：启动与验证

配置写完后，重新启动 OpenCode，随便打开一个代码文件，输入一段注释或者一个函数名，看补全是否正常触发。

如果一切正常，你会在输入时看到模型返回的补全建议。如果失败，观察错误提示属于哪一类：

• 401 或 403：首先是认证问题，检查 Key 和请求头。
• 404 或 400：通常是模型名称或请求格式不匹配。
• 超时：服务不可达，或者模型加载太久。
• 乱码或截断：可能是编码问题，也可能是maxTokens太小。

还有一个很实用的验证方式：在 OpenCode 的日志面板里查看实际的请求信息和报错原因。很多问题在界面里只显示“请求失败”，但日志里会明确告诉你具体是哪一步失败了。

4.5 第五步：按需微调参数

跑通之后，你可以开始微调参数，让输出更符合场景。

如果是日常代码补全，把temperature保持在 0.2 附近，输出稳定最重要。如果是用 OpenCode 做技术方案讨论、代码 review 总结这类偏对话的任务，可以把temperature调到 0.5 到 0.7，让表达更丰富。maxTokens则根据任务类型调整：短注释可以设小一点，长函数生成需要更大空间。

微调参数时，一次只改一个变量，改完立即验证效果。如果你同时改了三个参数，出了新问题你根本不知道是谁引起的。这个习惯被我反复验证过，是真的能省时间。

5. 常见问题排查实录

5.1 401/403 认证失败

认证失败是最常见的自定义模型配置问题，OpenCode 的界面上通常会显示 401 或 403。

我通常按这个顺序排查。先确认 API Key 是否正确，注意复制时别带上多余的空格或换行。再确认识别方式，有些服务要求Authorization: Bearer <key>，有些要求自定义 Header，比如X-API-Key，这取决于服务端实现，OpenCode 里一般可以通过headers字段指定。

还有一种情况：本地模型服务本身没有鉴权，但配置了一个错误的 Key，客户端仍然会带着这个 Key 请求，只是服务端忽略它，所以也能通。但如果服务端校验 Key，而 OpenCode 里没配或者配错，就会一直 401。

5.2 请求超时与服务不可达

超时问题分成两类：网络不可达和模型响应慢。

网络不可达的表现是请求一两秒内就失败。先 curl 测端口，确认地址是否正确、服务是否运行。如果是远程服务，还要考虑网络策略是否放行了这个端口。模型响应慢的表现是请求发出去之后一直转圈，最后超时。这种情况通常是本地模型正在加载、显存不足导致推理变慢，或者服务端并发太高。

处理办法也很直接：把 OpenCode 的timeout适当调大。很多本地模型首次请求要加载权重，30 秒都不够，调到 120 秒是很常见的操作。同时去模型服务端日志确认请求是否真的到了，如果根本没到，问题在网络或地址；如果到了但响应很慢，问题在模型服务本身。

5.3 模型名称报错

模型名称报错，通常提示“model not found”或者 404。这个问题的根源几乎都是名称不精确。

模型名称不是给人看的标签，而是服务端的唯一标识符。你以为是my-model，服务端实际注册的是my-model-v1.2，多一个小版本号就完全匹配不上。

正确做法是：用模型列表接口把真实名称拉出来，然后完整复制。有些服务的模型名称区分大小写，my-model和My-Model也不同，复制时不要手动重新输入。模型名称确定后，OpenCode 配置里填写的值必须一字不差。

5.4 上下文长度超限

上下文超限的典型表现是，请求发送后服务端返回类似“context length exceeded”的错误，或者补全到一半戛然而止。

原因有两个方向。一是maxTokens设得太大，大于模型服务允许的上限；二是输入内容太长，加上生成内容后超出模型窗口。

解决办法：先查模型支持的最大上下文窗口，把maxTokens调小一些。如果输入内容确实很长，考虑启用客户端的自动截断，或者把过长的文件拆成多次对话。很多模型超限不是一次就爆，而是连续对话把历史记录累积得太长，这种情况清理一下会话上下文就能恢复。

5.5 输出乱码或截断

输出乱码在自定义模型配置中不算高频，但一旦出现很影响心情。

乱码大概率是编码问题。如果模型服务返回的内容是 UTF-8，而 OpenCode 端解析时用了其他编码，就会出现中文乱码。这种情况先在服务端用 curl 直接请求一次，看返回结果是否正常，以此判断问题在服务端还是客户端。如果 curl 正常而 OpenCode 乱码，检查配置文件里有没有强制指定字符集，再尝试更新到最新版本。

输出截断则多见于maxTokens设置太小，或者模型在生成长代码时遇到上下文瓶颈。解决方式是调大maxTokens，同时确认上下文窗口是否足够。

5.6 配置不生效的几类原因

“我改了配置，但 OpenCode 好像没反应”，这是最常见的困惑。我把原因整理成一张速查表：

配置不生效的排查原则只有一个：确认 OpenCode 实际读到的配置是什么，而不是你“以为”的配置是什么。命令行工具是唯一可靠的确认手段。

6. 进阶玩法与避坑心得

6.1 用日志定位问题

当错误信息不够用的时候，日志是最有力的工具。多数版本支持设置日志级别，比如：

opencode --log-level debug

开启 debug 日志后，OpenCode 会输出详细的请求地址、请求头、响应状态和错误详情。我遇到最难排查的一次，是自定义模型服务对某个 Header 大小写敏感，界面只显示“请求失败”，日志里却明确记录了服务端返回的错误信息，一秒钟就定位了问题。

排查建议是：先开 debug 日志复现故障，再根据日志逐项比对配置。不要凭感觉猜，日志会告诉你真相。

6.2 设计降级与回退策略

自定义模型服务不可能永远稳定。本地服务可能因为显存不足崩溃，远程网关可能因为限流拒绝请求。一个成熟的使用习惯是准备一个备用模型。

我在前面提到过providers多模型配置。遇到主模型故障时，我会通过模型切换入口快速切到备用模型，而不是停下来重配。如果团队的 OpenCode 支持自动重试，也可以配置当主模型失败时自动回退到备用模型。

这个策略在关键演示、紧急提交时特别有用。宁可响应慢一点，也不能整个工具不可用。

6.3 成本与并发控制

接自定义模型后，另外一个容易被忽略的问题是成本与并发。

如果是按 token 计费的远程 API，maxTokens设置过大会直接推高成本。我在团队内部做过一次统计，把maxTokens从 4096 降到 2048 之后，月度成本下降了接近一半，而大部分补全任务根本没觉得变短。

如果是本地部署服务，并发控制比成本更重要。显存是有限的，并发请求一多，轻则服务变慢，重则直接 OOM。建议在模型服务端限制并发数，同时在 OpenCode 侧避免同时发多个长对话请求。

6.4 我的几个小建议

最后分享几条攒下来的经验。

配置文件里不要内联真实 Key，哪怕只是个人项目，也建议走环境变量。这是我吃过亏之后形成的铁律。

每次改配置只改一个变量，验证通过再改下一个。多变量同时修改，排查问题时会陷入“不知道是谁导致”的困境。

把配置模板纳入项目仓库，但把 Key 排除在外。新成员拉下项目后，只需要配置自己的环境变量就能跑通，团队接入成本会低很多。

先在命令行用 curl 验证服务，再动 OpenCode 配置。这条听起来基础，但我每次跳过他都会付出时间代价。

模型名称永远是复制，不是手打。大小写、版本号、命名空间，任何一个差异都是坑。

7. 写在最后：一点个人体会

OpenCode 自定义模型配置这件事，说难不难，说简单也不简单。我自己最初配置时，卡在模型名称上整整一下午，后来发现服务端的模型列表里有个版本后缀，而我一直填的是不带后缀的“简化名”。从那以后，我养成了一个习惯：接任何模型服务，第一件事永远是拉取模型列表，而不是急着写配置。

现在这个工具几乎是我日常开发的主力入口。自定义模型配置带来的不是一次性的“能用”，而是长期的“可控”——数据安全、成本、模型选择都掌握在自己手里。也许你刚开始配置时会遇到各种报错，但请相信，绝大多数问题都能通过日志和命令行定位到具体原因。按我上面这套步骤走一遍，你的 OpenCode 应该就能稳定跑在自定义模型上了。如果还有奇奇怪怪的问题，欢迎用日志里的关键信息去社区里搜，大概率能找到同路人。