企业官网建设流程全解析

1. 先搞清楚：OpenCode 和 GLM 是怎么凑到一起的

OpenCode 配 GLM 这套玩法，说白了就是在一个开源终端工具里，用 GLM 大模型当编码大脑，让你用自然语言驱动整个开发流程。OpenCode 本身不提供任何模型能力，更像一个调度器加执行器；GLM 负责理解意图、生成代码、分析报错、调用工具。两者通过标准模型 API 对接，配置好之后，你就能在终端里像指挥一位工程师一样干活。

很多第一次接触的人容易把它和"代码补全"混为一谈，实际差距很大。代码补全是你写一行它猜下一行；OpenCode 这类 Agent 是你描述一个目标，它自己去读代码、改文件、跑命令、看结果、再迭代。GLM 在代码生成、工具调用、长上下文理解上的表现，恰好撑得起这套工作流，这也是这套组合最近讨论度明显上升的原因。

1.1 OpenCode 到底帮你解决了什么问题

OpenCode 解决的第一个痛点是场景割裂。用图形化 IDE 加 AI 插件时，你往往要在编辑器、终端、浏览器、文档之间来回切换；遇到编译报错，得把错误信息复制粘贴给 AI，再把 AI 的改法粘回去。OpenCode 直接跑在终端里，和 Git、Shell、测试命令处在同一个环境，Agent 改完代码自己跑测试，出了问题自己读日志，人和 AI 的协作半径被大幅缩短。

第二个痛点是上下文碎片化。IDE 里的聊天窗通常只知道你当前打开的那几个文件，而 OpenCode 里你可以一句话让它读整个目录、追踪调用链、理解工程结构。对老项目、多模块仓库、别人留下没有文档的代码，这种全局理解能力比补全式工具实用得多，尤其在跨模块改动时，AI 能直接找到你口头描述不清的那个函数到底在哪个文件里。

第三个痛点是过程不可控。很多人担心 AI 把代码改坏了也不知道。OpenCode 的 Agent 在改文件、执行命令前会请求权限，每一步在终端里都可追溯，配合 Git diff 能很清楚地看到它动了什么。这种透明度对想在生产项目里用 AI 的人来说很重要。适合它的使用者也很明确：后端、全栈、运维、SRE，以及任何愿意把日常开发流程收敛到命令行的人。纯前端设计稿驱动的工作流当然也能用，但收益更多体现在逻辑密集、命令密集的开发场景。

1.2 GLM 系列模型为什么值得放进编码 Agent

把 GLM 放进 OpenCode，我看来有几个实际理由。首先是编码链路能力。GLM 近几代模型在函数调用、指令遵循和长任务执行上的稳定性进步很明显，Agent 场景恰恰最吃这三样。模型要能准确地按约定格式输出工具调用、在长上下文里不丢前面的约束条件、在被问到"改过哪里"时还能记得住，这些都不是单纯"写代码能力强"能覆盖的，需要整体推理和状态管理能力。

其次是对接成本低。GLM 开放平台的 API 兼容 OpenAI 体系，OpenCode 这类工具基本填一个网关地址和 API Key 就能接入，不需要为它写专属适配层。社区里也有对应的 AI SDK 适配包，配置起来甚至比一些自建网关还省事。再就是使用门槛和服务稳定性。对国内开发者来说，直接用国内模型服务，网络链路更稳定，不需要费劲处理海外 API 的连通性问题；文档、工单、计费也都是中文语境，出了问题好沟通。

价格方面，GLM 的 API 计费相比部分海外旗舰模型要友好，尤其是做高频单测、批量重构这类"token 烧得快"的任务时，差距会直接体现在账单上。当然它也不是没有缺点，后面我会专门说上下文管理、限流和成本控制上要注意的地方，这些都是实际跑起来才会遇到的问题。

2. 开工准备：安装、密钥、选模型

在写配置之前，先把三件基础事情做好：装好工具、拿到密钥、选对模型。很多后面排查半天发现的问题，都是这三件事没做扎实导致的。

2.1 安装 OpenCode

如果你有 Node.js 环境，最简单的方式是 npm 全局安装：

npm install -g opencode-ai

安装完执行：

opencode --version

能正常输出版本号就说明装好了。如果机器上没有 Node.js，可以先装 Node，或者参考官方文档用脚本方式安装。我不太建议装完就不管了，这个工具迭代速度很快，隔一两个月就可能有配置项变化，定期升级能少踩很多版本相关的坑。如果你在容器、远程服务器或者 Windows 的 WSL 里使用，安装思路一样，只要保证终端里能启动交互界面、机器能访问模型服务的 API 地址即可。

2.2 申请 GLM 的 API Key

去 GLM 模型的官方开放平台注册账号，完成身份认证，然后在控制台创建 API Key。这一步有几点实际经验：

• API Key 创建后通常只完整显示一次，创建完要立刻保存到密码管理器里，别等用到时才去找；
• 如果平台支持创建多个 Key，尽量给编码工具单独建一个，方便以后单独关停或轮换；
• 提前把账户的充值或套餐开通好，否则配置再正确也可能因为欠费而鉴权失败。

如果你已经在别的地方用过 GLM 的 API，这个 Key 直接复用就行，不用重复创建。

2.3 模型怎么选：一张表说清楚

GLM 系列不是"一个模型打天下"，不同型号的定位、上下文长度、价格都不一样。我平时是这么分的：

不要一上来就默认选参数最大的模型。我的经验是：把 Agent 的主模型设为 GLM-4.6，简单的子任务显式切到便宜型号，综合体验和成本都能兼顾。

3. 接入实操：把 GLM 配成默认 Provider

配置 OpenCode 接 GLM 有两种主流方式：交互式配置和手写配置文件。新手建议先走交互式，想做到团队可复现再改用配置文件。

3.1 方法一：交互式引导配置

在项目目录里直接运行：

opencode

打开交互界面后，先用/models进入模型管理。这里通常能看到已内置的模型提供商列表，如果列表里有 GLM 对应条目，直接选中，再按提示粘贴两样东西：

• Base URL：GLM 开放平台给出的网关地址，一般在控制台能看到，形如https://open.bigmodel.cn/api/paas/v4，具体以你页面上显示的为准；
• API Key：上一步创建的密钥。

如果列表里没有现成条目，或者版本较老，可以运行：

opencode models

这个命令会启动命令行向导，让你手动添加自定义 provider，过程类似：填名字、网关地址、密钥、模型列表。配置完成后回到/models，应该能看到glm-4.6等条目，选中后回到会话，底部状态栏会显示当前模型名。如果这一步没看到 GLM 相关条目，可以走下面的配置文件方式，适用范围更广。

3.2 方法二：手写配置文件

想把配置提交到仓库里、让团队统一复用，推荐在项目根目录放一个opencode.json。以下是一份实测可用的配置模板：

{ "$schema": "https://opencode.ai/config.json", "provider": { "glm": { "npm": "@ai-sdk/zhipu-ai", "name": "GLM", "options": { "baseURL": "https://open.bigmodel.cn/api/paas/v4", "apiKey": "{env:ZHIPU_API_KEY}" }, "models": { "glm-4.6": { "name": "GLM-4.6" }, "glm-4-flash": { "name": "GLM-4-Flash" } } } } }

逐个字段解释一下：

• provider.glm：自定义 provider 的 ID，可以随意命名，但建议和模型官方名称保持一致，方便识别；
• npm：OpenCode 底层的 AI SDK 会通过这个包发起请求，@ai-sdk/zhipu-ai是官方适配包。如果你更想走通用 OpenAI 兼容格式，换成@ai-sdk/openai-compatible也可以；
• options.baseURL：模型网关地址，以控制台显示的为准；
• options.apiKey：这里用{env:ZHIPU_API_KEY}引用环境变量，而不是直接写死明文密钥，原因后面细说；
• models：注册这个 provider 下真正用到的模型列表，写多了反而让切换菜单变得冗长。

写完配置后把密钥放进环境变量：

export ZHIPU_API_KEY="你的API Key"

然后重新启动opencode。注意环境变量要在启动 OpenCode 之前就存在，改完没生效，先检查是不是当前 shell 里没有 export，或者终端没重启。这个坑我踩过不止一次，后面在排查部分会细说。

3.3 首次启动：怎么验证真的通了

配置完别急着让它写大功能，先做一次冒烟测试。在 OpenCode 会话里输入：

读取当前项目的 README 文件，用三句话概括这个项目是做什么的。

观察三个点：

• 模型是否返回了合理总结，说明 API 鉴权、网络、模型名都没问题；
• 界面是否显示模型名和 token 消耗，说明计费接口和模型状态正常；
• 如果让它改文件，是否弹出权限确认，说明 Agent 的文件操作链路是通的。

如果第一步就报错，大概率是鉴权或网关地址问题，可以直接跳到第五节查排障。第一次跑通这个闭环很重要，它验证的不只是"能不能用"，而是你后续所有工作流的地基。

4. 实战姿势：让 Agent 从"能对话"到"能干活"

配置通了只是第一步。我在实际使用中发现，OpenCode 这类 Agent 工具真正的分水岭，在于会不会用工作流式的交互方式，而不是把聊天框当成搜索引擎用。

4.1 先规划后动手：别让模型凭直觉开写

面对一个较大的需求，直接丢一句"帮我实现某某功能"，模型往往会凭直觉开写，写到一半发现和现有代码风格冲突，或者漏了边界条件。OpenCode 支持先让模型产出执行计划，典型做法是用/init或者在提示词里明确要求"先给出实施计划，列成清单，我确认后再逐步执行"。

这样做的收益非常直观：模型在计划阶段就能全局扫描项目结构、识别入口文件、预判影响面，后面每一步都是执行而非探索，跑偏的概率大幅下降。我自己的习惯是，任何超过半小时人工工作量的任务，都会先让它产出计划并保存到一个 markdown 文件里，既方便自己 review，也方便后续把它作为新会话的上下文。这个习惯对长任务的收益，比任何参数调优都明显。

4.2 把命令行权限管好，别当甩手掌柜

OpenCode 的 Agent 可以执行任意 shell 命令，这是它能力强的根源，也是最大的风险点。不同版本的默认权限策略不完全一样，建议你主动确认一下。我的建议是：

• 读类命令（ls、cat、grep）可以自动放行；
• 写类命令和构建命令（npm install、make、git commit）保持每次确认；
• 危险命令（git push、rm -rf 这类）一律保持拦截，手动执行。

分享一个教训：让 Agent 自动跑测试时，它可能顺手执行了构建脚本，把依赖更新了一遍，导致本地环境和 CI 不一致。所以在让它跑命令前，最好在提示词里加一句"只运行必要的验证命令，不要安装或更新依赖"。这些约束听起来像废话，但对指令遵循敏感的模型来说，写上和不写，结果差别非常大。

4.3 用 Git 和测试把这个循环闭环

Agent 改代码不是改完就结束，一定要让它自己验证。标准的闭环是：改代码、跑相关测试、看 diff、修问题、再跑测试。你可以直接这样下指令：

修复 auth 模块的登录超时问题，先写一个能复现的测试，再修实现，最后跑通相关测试用例，并给我一个简洁的 commit message 建议。

如果项目里还没有测试，让 Agent 先补一个最小可复现用例，往往定位速度比人工翻日志还快。跑测试这一步很重要，它让模型从"生成代码"升级成"对结果负责"，体验完全不同。在 Git 工作流方面，OpenCode 默认能看到仓库的 diff 和状态，它可以基于这些信息判断自己改了什么。我习惯让 Agent 做小步提交、把改动拆成多个语义清晰的 commit，避免一上来就是一个大杂烩提交。

4.4 团队复用：配置进仓库，密钥永远不进仓库

配置文件里引用环境变量，就是为了让opencode.json可以安全地提交到 Git。团队成员在自己机器上设置ZHIPU_API_KEY即可，不用改公共配置。如果你在公司内部使用，还可以约定统一的模型策略（主模型、权限级别、默认参数），把配置作为工程规范的一部分维护。

团队合作时还有一个实用技巧：在项目里放一个说明文件，把编码规范、目录约定、测试命令都写进去，然后让 Agent 每次开工前先读它。这样一个新同学加入项目，用 OpenCode 干活的产出质量能被直接拉齐，不用反复口头交代项目上下文。

5. 常见问题与排查技巧实录

这一节是从真实使用中整理出来的问题清单，很多坑不看不知道，看到了能省半天时间。

5.1 鉴权类问题：先分清是 Key 的问题还是网关地址的问题

遇到任何"连不上"的报错，我建议的排查顺序永远是先绕过 OpenCode，直接用 curl 打一次 API，确认模型服务本身是否可用。这一步能把问题快速区分为"模型侧"还是"工具侧"。curl 测试通过而 OpenCode 失败，那就是配置或版本问题；curl 也失败，那就是 Key、余额、网络的问题。

一个参考命令：

curl https://open.bigmodel.cn/api/paas/v4/chat/completions \ -H "Authorization: Bearer $ZHIPU_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model":"glm-4.6","messages":[{"role":"user","content":"ping"}]}'

地址以你控制台显示的为准。这个命令能通，说明网络、鉴权、余额、模型名都没问题，剩下就是 OpenCode 侧配置的事。

5.2 模型名没对应上：宣传名和 API ID 是两回事

这里特别强调一下：GLM 开放平台的模型宣传名和 API 里的模型 ID 经常不完全一样。比如宣传名可能写"GLM-4.6"，API 里对应的 ID 可能是glm-4.6或者带版本后缀的写法。不要凭记忆写模型名，以控制台显示的 API 模型 ID 为准。这个坑非常常见，很多人报 404 其实只是名字大小写或者后缀差了一点。

5.3 上下文被"污染"，不是模型的错

我见过不少"GLM 越用越蠢"的反馈，排查下来八成是上下文爆炸。长会话里塞满了大量工具返回结果、大文件内容、无关讨论，模型要在海量噪声里找重点，表现上就是回复变敷衍、指令遵循变差。这跟模型能力没关系，纯粹是使用姿势问题。解决方式很简单：任务告一段落就开新会话，把必要结论沉淀到文件里，别让一个会话从早上活到晚上。

6. Token 成本控制与参数调优

很多人用 Agent 工具，最大的心理障碍是"怕烧钱"。事实上，只要理解 token 的消耗机制，完全可以把成本压到很低。

6.1 先搞清楚钱到底花在哪了

Agent 的 API 计费大头从来不是那几行输出，而是输入。每轮对话都要把整段历史重新发送给模型，加上工具执行结果、文件内容，一轮下来可能吃掉几千 token。最烧钱的三个动作：

• 让它读大文件，一次可能就消耗大量 token；
• 循环调用工具，每次返回结果都算输入；
• 长会话不复位，对话轮数越多，每轮的历史成本叠得越厚。

理解了这三件事，"为什么我只是让它改一个小 bug 账单却涨了"的疑惑就解开了。改一个小 bug 可能需要五轮对话，每轮都带着之前所有的工具返回结果，成本自然上去了。

6.2 省钱三板斧

第一斧，按任务粒度开会话。一个小需求开新会话，一个大需求拆成"读代码"和"改代码"两个会话。第二斧，能用便宜模型就不用贵的。明确的小任务，比如给代码补注释、格式化、写单元测试骨架，切到 GLM-4-Flash 这类轻量型号。第三斧，让模型少读、精读。别让它全仓库扫描，先让它看文件清单和项目结构，确定目标文件后再精读。

这三招用下来，成本通常能降到原来的三分之一。我见过最夸张的一次，只是把一个几十万行的目录让 Agent 做了一次全量索引，一次会话的输入 token 就抵得上平时一个星期的用量。从那以后，"先列目录再精读"就成了我的铁律。

6.3 参数怎么调

在模型配置里，有几个参数值得关注：

• temperature：编码任务保持低值，默认就够了，调高只会让代码风格更飘；
• max tokens：设置输出上限，防止单次回复无限生成，尤其在让它写长文档时有用；
• 项目说明文件：把团队规范写进去，比每次重复强调效果稳得多。

还有一条容易忽略的：不要同时开多个并发 Agent 跑同一个仓库，不仅成本翻倍，还容易因为同时改同一个文件造成冲突。真要并行，也请按模块拆分，各跑各的目录。

7. 我用下来的几点实在体会

最后说点不写在官方文档里的体会。第一次配 OpenCode 和 GLM 时，我花时间最多的地方不是写配置，而是理解"配置和会话分离"的设计：配置文件负责 provider 和模型定义，真正的会话上下文在每次启动时实时读取。所以改了配置文件，旧会话不一定立刻生效，重启才能看到新效果。这个认知帮我少走了很多弯路。

真正让我坚持用下来的是它的工作流价值。它不是一个"写代码速度更快的补全插件"，而是把"理解需求、搜索代码、定位问题、修改验证"这条链路压缩到对话里。对一个维护老项目、跨模块需求多的开发者来说，省下的不是敲键盘的时间，而是来回切换上下文的心智成本。

如果你准备上手，我建议从一个小而真实的任务开始，比如给现有模块补测试、修一个已知 bug，别一上来就挑战全新项目。跑通一次完整闭环后，你会对它的能力边界有直观认识，也知道哪些任务该交给它、哪些任务必须自己动手。等习惯了，再逐步在团队里铺开。这个组合后续可以扩展的方向不少，比如把配置文件放进统一的 dotfiles 管理、在 CI 里用它做只读代码审查、针对不同编程语言分别定义提示词模板。慢慢玩，你会找到属于自己的那套最佳实践。