opencode接入智谱GLM：code plan配置完整指南

前阵子折腾opencode，想把智谱GLM接进去做日常编码，结果在“code plan”这个配置上卡了整整一晚上。查了半天文档和社区帖子，发现大多数人只告诉你“配一个api key就行”，但真正跑起来后，模型调用策略、计划名称、环境变量这些细节才是决定你能不能稳定用下去的关键。这篇就把我最终跑通的完整方案写出来，包含配置代码、实测步骤和我踩过的坑。如果你也想让opencode里跑GLM的code plan，照着做基本不会翻车。

1. 先说清楚：opencode、GLM和code plan到底分别是什么

1.1 opencode不是另一个IDE，它是一个Agent式的编码终端

先给没接触过的朋友补个基础。opencode是一个跑在终端里的AI编码助手，它有别于传统的IDE插件，它的工作方式更接近一个Agent：你给它一个任务，它会自动规划步骤、调用工具、读写文件、执行命令，最后给出结果。你可以在命令行里单独使用，也能作为VSCode的扩展内嵌到编辑器里。和Codex CLI这类工具定位很像，但它更强调多提供商和多模型的组合能力。

我选择它的原因很简单：我不想被某一个模型厂商绑死。今天GLM发布新模型，明天通义、Kimi出了更强版本，如果不换一套工具，就得在多个IDE插件之间来回切。opencode把模型提供商抽象成了一层配置，换模型等于改配置文件里的一行，这个体验对于长期做技术选型的人来说太重要了。

1.2 GLM的编码能力：为什么值得在opencode里单独配一份

可能有人会问：直接用官方的Codex或Copilot不香吗？我的看法是，很多场景下的编码助手需要的不是“最聪明”，而是“最合适”。智谱GLM系列在国内模型里属于较早把编码能力单独做成产品线的，GLM-4系列在代码生成、单测补全、中文注释生成上表现都比较稳，而且它的计费比很多国际模型友好，日常小任务量下基本花不了几块钱。更关键的在于，GLM的接口兼容OpenAI的调用风格，接进opencode这种工具时，适配成本非常低。

我在opencode里配完GLM之后，明显感觉到中文需求理解的完成度比很多只训练英文语料的模型高。比如让它“给这个接口补一个批量删除的确认逻辑”，它会先理解“确认逻辑”在中文产品语境里通常指二次弹窗和权限校验，而不是简单删掉接口。这些小细节在日常开发里很加分。

1.3 code plan是什么：模型调用策略，不是单独的模型名

这是最容易误解的一点。第一次看到“code plan”这个词，我还以为这是GLM新出的某个模型型号，查了一圈才发现，在opencode的配置体系里，plan指的是对一个模型在编码场景下的调用方案。简单说，你在provider下面定义好模型后，还可以再定义这个模型以什么plan来跑。plan可以指定具体的上游模型版本、采样温度、最大token数、是否开启推理模式、允许调用哪些工具等等。

为什么要单独拎出来一个plan？因为同一个模型在不同任务下的最优参数是不一样的。做代码生成时你希望温度低一点、上下文长一点；做闲聊总结时你又希望它温度高一点、更有发散性。如果每次都在prompt里苦口婆心教它，不如直接在配置层把参数固化下来。code plan就是专门为代码任务设计的一个预置参数组，在opencode配置里选中它之后，模型会以更适合写代码的方式工作。

这里需要留意的是，不同版本的opencode对plan的支持方式可能不太一样。老的版本可能只有model列表，新的版本会在model节点里多出plan字段。所以如果你打开的配置文件里看不到这个字段，先升级opencode版本，而不是怀疑自己写错了。

2. 配置前的环境准备：哪些东西没装好会白忙一场

2.1 Node.js和Git：opencode跑起来的最低要求

opencode本身是一个npm包，所以Node.js是必须的。我建议装LTS版本，不要装太新的奇数版本，否则遇到原生模块编译问题会很难受。Node安装好之后，用这两条命令确认：

bash复制node -v
npm -v

Git主要用于克隆仓库和opencode的部分工具调用。如果你平时已经在用git，基本不需要额外配置；如果机器上还没装，装好后记得跑一下 git --version 验证。opencode在读取项目文件、查看diff、生成提交信息时都会调用git，缺了它很多能力是静默失效的，不会报错，但输出会变得很奇怪。

2.2 拿到智谱API Key：注意计费和权限

接着是获取智谱的API Key。这一步不复杂，登录智谱AI开放平台，在控制台里找到“API Keys”，创建一个新key就行。创建的时候有个容易忽略的点：API Key对应的权限范围。有些key默认只开了一部分模型接口的权限，如果你后面调用code plan时被拒绝，先回控制台检查key有没有开通对应的模型服务。

拿到key之后，千万不要硬编码到配置文件里然后推到Git仓库。正确做法是写到环境变量里。我习惯在shell配置里加一行：

bash复制export ZHIPU_API_KEY="你的key"

然后在opencode的配置文件中通过 {{env:ZHIPU_API_KEY}} 引用。opencode运行时会把环境变量展开成真实的key，这样即使配置文件被分享出去，也不会泄露密钥。另外，智谱API不是完全免费的，注册后会有一定额度的体验包，但生产环境下建议先去计费页面看清楚单价，别等月底账单出来才后悔。

2.3 装好opencode本体并确认版本

安装opencode很简单，用npm全局安装即可：

bash复制npm install -g opencode

装好之后执行 opencode --version，如果能看到版本号就说明安装成功。我遇到过一种情况：命令明明执行成功了，但 opencode 指令找不到，这种通常是npm的全局bin目录没加到PATH里。解决办法是在终端里运行 npm config get prefix，然后把输出目录的bin子目录配置到PATH里。

版本号这点特别重要。我一开始用的老版本，配置文件里写plan字段怎么都不生效，后来升级到新版本，同样的内容瞬间就能识别。如果你看到opencode提示“config schema unknown field”，第一反应应该是升级，而不是删字段。

3. 从零到一：把GLM code plan写进opencode配置

3.1 找到正确的配置文件位置

opencode支持多级配置，常见的有全局配置和项目配置两种。全局配置一般在 ~/.config/opencode/opencode.json，项目配置则放在当前项目的 .opencode.json 或 opencode.json 里。如果两个文件都存在，项目配置会覆盖全局配置中相同路径的内容。

第一次不知道怎么找配置文件，可以直接在终端里输入 opencode config，它会自动帮你打开当前生效的配置文件路径，甚至生成一个带有schema提示的初始文件。这个命令是我用了很久才发现的好东西，比手动去翻目录省事多了。

配置文件本质上是一个JSON，但opencode也支持JSONC，也就是带注释的JSON。你可以在关键字段旁边加中文注释，下次回来看的时候不会一头雾水。不过要注意，如果编辑器没有JSONC支持，普通JSON里写注释是会报错的。

3.2 最简配置：一个能用的GLM code plan

下面这个配置是我实测能跑的版本，也是我推荐的最小可用配置。以智谱作为provider，并在模型节点里声明一个code plan：

jsonc复制{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "zhipu": {
      "npm": "@ai-sdk/zhipu",
      "name": "智谱GLM",
      "apiKey": "{{env:ZHIPU_API_KEY}}",
      "models": {
        "glm-4-plus": {
          "name": "GLM-4-Plus",
          "plan": "code plan",
          "reasoning": true,
          "temperature": 0.2,
          "maxTokens": 8192
        }
      }
    }
  },
  "model": "zhipu/glm-4-plus"
}

逐个字段解释一下：npm 字段告诉opencode去哪个SDK包加载这个提供商，智谱已经封装好了适配包，不用自己写请求逻辑；apiKey 我们引用了环境变量；models 下面定义了模型列表，这里的 glm-4-plus 是智谱平台上的模型标识符；plan 字段指定了这个模型跑的是哪个计划，这里的 code plan 对应我在模型中配置的code coding策略；最后的 model 是全局默认模型，意思是启动opencode后默认就使用这个配置。

需要注意，不同智谱模型标识符可能不一样。老用户可能记得 glm-3-turbo，新平台已经用 glm-4-flash、glm-4-plus、glm-4-long 这套命名了。拿不准的时候以智谱开放平台文档给出的model id为准，不要自己去猜。

3.3 更进一步：为code plan限定上下文和工具权限

只在model节点里写一个plan名字还远远不够，我们真正要配置的是code plan的行为。在我的配置里，我还额外声明了一个plans节点，用来定义code plan到底该怎么跑：

jsonc复制{
  "plans": {
    "code plan": {
      "description": "专用于代码生成和重构的计划",
      "temperature": 0.2,
      "maxTokens": 8192,
      "contextWindow": 131072,
      "tools": {
        "enabled": ["read_file", "write_file", "edit_file", "terminal_command", "search_files"],
        "disabled": ["web_search"]
      }
    }
  }
}

这样配置以后，只要模型绑定的是code plan，opencode就会用这套参数来调用模型。把温度调到0.2是为了让代码输出更稳定，减少随机发挥；上下文窗口设置成131072是因为GLM-4系列支持长上下文，让模型在重构大文件时能看见完整上下文；工具权限上，我关闭了web_search，避免它在编码过程中跑偏。

很多人不理解为什么工具权限也要管。举个例子，如果模型中保留web_search，它可能在分析一段代码时报了个错，然后自动去网上搜索解决方案。听上去积极，但搜索结果未必可靠，反而会让一次简单的代码修正变成漫长的连环对话。编码计划更适合严格限定在本地文件系统和终端命令上，减少不必要的噪音。

3.4 切换默认模型和code plan

配置写完后，怎么知道当前生效的是不是GLM code plan？在opencode交互界面里可以输入 /models，会列出所有可用的模型和plan组合。要切换默认模型，也可以在配置里修改 "model": "zhipu/glm-4-plus" 这一行。如果你希望日常聊天用另一个模型、写代码时切到code plan，那就在prompt里显式指定，比如 @glm-4-plus:code plan 帮我把这个服务改成依赖注入方式。这种指定方式可以避免每次手动切配置。

4. 跑通整条链路：命令行和VSCode里各来一遍

4.1 命令行模式下用code plan跑一个真实任务

配置完成后别急着打开编辑器，先在终端里验证一下最核心的能力。最简单的方式是进入交互模式：

bash复制opencode

进入后你会看到类似聊天窗口的界面，默认模型如果已经设置成GLM，直接输入一个需求试试。我习惯先用一个很小的任务验证，比如“读取当前目录下的README.md，用三句话概括项目作用”。这个小任务能同时验证模型调用、文件读取和系统提示词拼接是否正常。

如果交互模式一切正常，再试试非交互模式：

bash复制opencode run "写一个Python函数：输入一个目录路径，递归找出所有超过100MB的文件，并按大小倒序输出"

非交互模式适合集成到脚本里，也是很多CI场景会用到的方式。跑出来的结果如果是一次性输出，说明链路没问题；如果卡住或报错，大概率是配置里的plan参数有问题，回到第3章逐项排查。

4.2 在VSCode里接入opencode，把配置变成可视化操作

命令行再方便，多数人日常写代码还是在VSCode里。opencode提供了官方扩展，直接在扩展市场搜索“opencode”安装即可。装好之后，左侧侧边栏会出现opencode的图标，点开就是一个内嵌的对话面板。

扩展本身不需要额外配置API Key，因为它会读取你本机opencode的配置文件。也就是说，你在第3章配置好之后，VSCode里直接就能用。这也是我推荐先配好命令行再装扩展的原因——避免两边各自维护一套配置，最后对不上。

在VSCode面板里，模型切换逻辑和命令行一样。但有一个体验更好的方式：命令面板里输入“OpenCode: Select Model”，可以快速在已配置的模型之间跳转。如果你要为当前任务特意切换到GLM code plan，这一步最便捷。

4.3 怎么确认当前请求真的走了GLM code plan

这是很多人的盲区。模型好像有响应，但到底走没走GLM？走的是不是code plan？如果不验证，后面遇到质量问题时根本无从排查。我有三个办法：

第一，在opencode的面板里输入 /status，它会显示当前会话使用的provider、model、plan名称。第二，看VSCode底部状态栏，扩展会展示当前模型的短标识，比如 zhipu/glm-4-plus code plan。第三，去智谱开放平台的调用记录页面，里面能看到每次请求的模型名称、token消耗和响应时间，比自己猜靠谱得多。

如果发现自己明明想用code plan，状态栏却显示的是default plan，多半是配置里的model名称写得不精确，或者有两个provider定义重名导致匹配错乱。这种问题在配置文件中用全文搜索查一下model id，基本就能定位。

5. 配置过程中我踩过的几个坑：照着避雷

5.1 环境变量没生效：API Key报错的第一元凶

我在刚配置时犯的最基础错误就是，把API Key写进了配置文件，但没注意引用的环境变量压根没导出。因为opencode在图形界面启动时，可能不会加载你shell里新增的那一行。如果你是在VSCode的集成终端里启动的，需要重启VSCode或者重新source一下配置文件，环境变量才会生效。排查方法是直接在终端里运行 echo $ZHIPU_API_KEY，如果能打印出key但opencode还是报401，再考虑配置里的引用格式问题。

5.2 模型ID对不上：400错误的常见原因

智谱的模型ID更新得比较快，网上很多教程写的是老ID，照抄后调用直接返回400。比如某个历史文章让你写 glm-4，但当前平台实际需要 glm-4-plus 或 glm-4-flash，这就会造成模型不可用。我的经验是：遇到400错误，第一反应不要调参数，先查模型ID是否正确。到智谱开放平台文档页直接复制当前可用的model id，粘贴进opencode配置，再试一次，大概率能解决。

5.3 plan名称大小写：看似小问题，实际很折腾

opencode的plan名称匹配是区分大小写的，而且空格也算。我一开始在模型节点里写的是 code plan，但在plan定义里写的是 Code Plan，结果运行时opencode报找不到对应plan，然后默认回退到default参数，外界看起来“能用”，但温度、工具权限全都不对。所以在配置里凡是写到plan名称，都要保持一致，建议直接统一用小写加空格，比如 code plan，并且复制粘贴而不是手动敲。

5.4 本地代理把请求拦截了

这一点比较隐蔽。如果你本机开启了代理类工具，部分流量会经过代理转发，而代理如果没有放行智谱的API域名，就会出现频繁超时或连接重置。我在配置时遇到过一次，挂上调试日志后看到请求一直卡在TLS握手阶段，最后才发现是代理的规则问题。解决办法是在代理工具里把智谱API域名加入直连列表，或者在启动opencode时临时关闭代理。如果在企业内网，还需要确认防火墙是否放行了对应的接口地址。

5.5 配置文件生效顺序：改了半天没变化的真相

opencode的配置优先级是：项目配置覆盖全局配置。你可能改的是全局配置，但项目根目录里恰好有个 .opencode.json，里面把某个字段设置成了别的值。或者反过来，你以为改的是当前项目配置，实际上打开的是全局那份。判断当前生效配置的最快方式是用 opencode config 命令，它会明确告诉你加载了哪些文件和合并后的结果。改完配置后记得重启opencode，很多字段是启动时加载的，运行中修改不会热更新。

我把这几个高频问题整理成了一个小表，方便你对照排查：

6. 让code plan真正好用起来的几个小技巧

6.1 把常用参数沉淀到全局配置

如果你跟我一样有多台开发机，或者经常在不同项目间切换，就不该在每个项目里重复维护一套配置。我的做法是：在全局配置里定义好智谱provider和code plan，项目配置里只保留那些真正跟项目相关的指令和自定义skill。这样项目配置变动时，不会影响其他项目的模型参数。

6.2 配合skills机制扩展代码审查能力

opencode支持skills，也就是给模型附加一些固定的行为模板。我专门写了一个“代码审查”skill，里面规定了审查时要关注安全漏洞、异常处理、资源泄漏这三类问题。配合GLM code plan使用时，模型会自动带着这套审查逻辑去读代码，输出质量立刻上了一个台阶。如果你的opencode版本支持skills，强烈建议把日常重复的prompt整理成skill，比每次手打要稳定太多。

bash复制opencode skills import code-review

6.3 控制成本：为code plan设置预算意识

GLM虽然便宜，但不代表可以无限挥霍。特别是使用code plan时，如果设置了大上下文窗口，一次高消耗请求的token数量会非常惊人。我的习惯是：日常小任务用flash模型，跑长上下文重构或代码审查时才切到plus模型。在opencode里可以用 /model 快速切换，不用改配置文件。另外留意会话中每个请求的token统计，opencode会在响应后显示prompt tokens和completion tokens，看到超过预期就检查一下是否是上下文被历史对话撑爆了。

6.4 找回历史会话：别再把对话留在终端里吃灰

opencode的会话默认是可以归档和查询的。有时候一个问题讨论到一半，第二天想接着聊，但又不想让VSCode一直开着。我一般用 opencode archive 把当前会话归档，之后在面板里通过历史记录重新打开。热词里有人问“opencode归档的对话到哪了”，其实就是放在本地会话目录下，没有同步到云端。如果换了电脑，记得把这个目录也纳入同步。

6.5 我的最终配置习惯

最后分享一下我个人用下来最舒服的组合：默认模型设为 glm-4-flash，用于快速问答和生成简单代码；code plan绑定到 glm-4-plus，专门处理复杂重构、跨文件修改和代码审查；在项目里额外装一个commit message skill，让模型按照约定式提交规范生成提交信息。这套组合日常使用很稳定，成本也可控。写代码时偶尔遇到模型思路不对，我会直接输入 /new 重置会话，避免让前面的错误方向干扰后续输出。

配置opencode接GLM并没有想象中那么玄乎，核心就是把provider、model、plan这几层关系理清楚。一旦跑通，后面换模型、调参数都只是改配置文件的事。希望这篇经验能帮你少走几个弯路。