OpenCode 中文教程：安装、GLM / OpenAI 兼容模型配置与真实任务实测

OpenCode 最近出现在越来越多开发者的终端截图里：开源、能接多家模型、既有 TUI 又有桌面端，看上去像是一个更自由的 AI 编程入口。

但真正开始配置时，问题很快就来了：npm 包到底叫什么？opencode.json 放在哪里？国产模型能不能接？“权限询问”是不是等于安全沙箱？免费模型出现在列表里，为什么运行时仍可能失败？

我没有直接整理一篇功能清单，而是在隔离目录安装 OpenCode 1.18.18，验证 CLI、配置解析和一个最小代码修复任务。最终结果有成功，也有一个很有代表性的失败样本。

先看实测结果

测试环境如下：

任务很简单：sum() 错把加法写成减法，测试期望 [2, 3, 5] 得到 10，实际得到 -10。我要求 OpenCode 先读测试，只做最小修改，再运行 npm test。

使用 opencode/big-pickle 后，它依次查找并读取三个文件，把：

return values.reduce((total, value) => total - value, 0);

改成：

return values.reduce((total, value) => total + value, 0);

随后执行测试，输出 tests passed。整次命令墙钟时间为 36.84 秒。

这只能证明当前版本在这个小任务里完成了“定位—编辑—验证”闭环，不能证明它在大型仓库里一定更快或更好。更有价值的是失败样本：opencode models opencode --verbose 能列出 ling-3.0-tiny-free，但实际调用返回：

Error: Model ling-3.0-tiny-free is not supported

因此，模型出现在目录里，不等于当前客户端、账号状态和服务端组合一定可用。选择模型后仍要跑一次真实最小任务。

OpenCode 是什么，适合谁

OpenCode 官方把它定义为开源 AI coding agent，可运行在终端、IDE 和桌面端。它支持多会话、LSP、会话分享以及多家模型 Provider。官方页面截至本文核验时展示约 19.5 万 GitHub Stars；这个数字会变化，只能作为热度快照，不能代替质量判断。

它更适合以下开发者：

• 希望在同一个客户端切换不同模型，而不是绑定单一厂商；
• 已有 OpenAI-compatible API、企业网关或本地模型；
• 喜欢终端工作流，但也希望保留桌面端和 IDE 选择；
• 愿意自己管理 Provider、权限、成本与配置文件。

如果你只想注册后立即使用、不想理解模型端点和权限边界，配置自由度反而会增加学习成本。

安装 OpenCode

官方提供一键安装脚本：

curl -fsSL https://opencode.ai/install | bash

使用 Node.js 包管理器时，包名是 opencode-ai：

npm install -g opencode-ai

macOS 或 Linux 也可以使用官方 Homebrew Tap：

brew install anomalyco/tap/opencode

官方说明该 Tap 通常比 Homebrew 团队维护的通用 formula 更新更及时。Windows 可以使用 Scoop 或 Chocolatey；官方文档更推荐在 WSL 中获得完整兼容性。桌面端目前仍带 Beta 属性，不应把它写成已经完全稳定的正式版。

安装后先记录版本：

opencode --version
opencode --help

版本很重要，因为 OpenCode 文档正在演进，不同版本可能出现字段名或 Provider 行为变化。不要从多篇旧教程拼接配置。

opencode.json 放在哪里

OpenCode 使用 JSON 或 JSONC 配置。项目级配置放在仓库根目录：

your-project/
├── opencode.json
├── package.json
└── src/

全局配置通常位于：

~/.config/opencode/opencode.json

建议给配置加入 Schema，编辑器可以提示字段：

{
  "$schema": "https://opencode.ai/config.json",
  "share": "disabled"
}

项目配置适合保存团队共同规则、模型别名和权限策略；个人密钥不要提交。全局配置适合个人默认模型和通用偏好。OpenCode 会合并配置，冲突字段由后加载的配置覆盖，因此排错时不要只看当前目录文件，要看最终解析结果：

opencode debug config

接入 GLM 或其他 OpenAI-compatible Provider

本文在 OpenCode 1.18.18 中实际解析通过的配置如下。示例只使用环境变量占位符，没有写入真实 Key：

{
  "$schema": "https://opencode.ai/config.json",
  "model": "glm/glm-4.7-flash",
  "share": "disabled",
  "provider": {
    "glm": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "GLM OpenAI Compatible",
      "options": {
        "baseURL": "https://open.bigmodel.cn/api/paas/v4",
        "apiKey": "{env:ZHIPU_API_KEY}"
      },
      "models": {
        "glm-4.7-flash": {
          "name": "GLM-4.7-Flash"
        }
      }
    }
  }
}

然后在当前终端注入密钥并启动：

export ZHIPU_API_KEY="请填写你自己的密钥"
opencode

这里要分清三个值：

• glm 是自定义 Provider ID；
• glm-4.7-flash 是模型 ID；
• https://open.bigmodel.cn/api/paas/v4 是 baseURL，不是带密钥的分享地址。

通用原理可继续阅读OpenAI 兼容 API 的 provider、baseURL 与模型名配置。如果上游走的是 OpenAI Responses API，而不是 Chat Completions，官方文档要求核对所用适配包，不能机械地套用 @ai-sdk/openai-compatible。

本文只验证了配置解析，没有使用真实 GLM Key 完成代码任务，因此不宣称“GLM 在 OpenCode 中已经实测成功”。发布前区分“Schema 能解析”和“模型真实可调用”，比贴一段看似正确的 JSON 更重要。

第一次运行前先收紧权限

可以从保守配置开始：

{
  "$schema": "https://opencode.ai/config.json",
  "share": "disabled",
  "permission": {
    "bash": "ask",
    "edit": "ask"
  }
}

allow、ask、deny 控制工具是否直接运行、询问或拒绝。但官方安全说明非常明确：Permission 是交互确认机制，不是安全沙箱。Agent 仍然可能执行 Shell、读写文件和访问网络；真正需要隔离时，应把它放进 Docker、虚拟机或权限受限的临时环境。

命令行里的 --auto 会自动批准未明确拒绝的权限，帮助文本也直接标注为 dangerous。生产仓库、客户代码或带密钥目录不应为了省一次确认就默认开启。

分享、隐私和 API Key 边界

OpenCode 默认分享模式是 manual，不会自动公开。但执行 /share 后，完整会话历史会同步到官方服务器，并生成“知道链接即可访问”的页面。敏感项目建议直接设置：

{
  "share": "disabled"
}

还要注意，关闭分享不等于所有数据都留在本机。提示词、相关代码上下文和工具结果仍会发送给你选择的模型 Provider，并受该 Provider 的隐私政策约束。

API Key 应放在环境变量、Secret 管理系统或权限受控的文件中。不要把真实 Key 写进 opencode.json、文章、截图或 Git。更完整的做法见大模型 API Key 安全存储与轮换。

如果启用 opencode serve 或 Web 模式，还要设置 OPENCODE_SERVER_PASSWORD 并限制监听地址。没有密码的服务端不应暴露到公网。

常见错误怎么排查

模型能看到，但运行时报不支持

先记录 OpenCode 版本，再执行：

opencode models PROVIDER_ID --verbose
opencode upgrade

核对模型状态、Provider ID 和客户端版本。目录是动态数据，不能替代真实调用验证。本文的 ling-3.0-tiny-free 就出现了“列表可见、运行不支持”。

401 或 403

执行 opencode auth list 检查凭据是否存在，再核对 Key 是否属于当前 Provider、是否有模型权限。不要把完整 Key 打进日志。

404 或模型不存在

检查 /connect 时填写的 Provider ID 与 opencode.json 是否完全一致；再检查 baseURL、模型 ID，以及 Chat Completions/Responses 所需适配包。

429、超时或 5xx

这通常属于上游额度、限流或服务状态问题。不要无限重试，可参考大模型 API 429、超时与 5xx 排查。

成本不清楚

OpenCode 提供 opencode stats 查看 Token 与成本统计，但免费模型、缓存读取和供应商账单口径可能不同。需要预算控制时，结合Token 成本核算与预算控制，并以 Provider 账单为最终依据。

OpenCode、Claude Code 和 Codex 怎么选

这不是速度或质量排行榜。模型、提示词、仓库规模、权限和网络都不同，没有同模型、同任务、同环境的对照测试，就不应给出“谁一定更强”的结论。

如果你的目标不是直接使用一个 Coding Agent，而是组合或替换模型适配器、工具、沙箱、会话与 Agent Loop，可以继续阅读DeepSeek Harness 中文安装、模型配置与插件实测。它更接近可扩展的 Agent 运行框架，与 OpenCode 的产品定位并不相同。

最终建议

OpenCode 值得尝试的核心，不是“又一个 AI 终端”，而是把客户端与模型 Provider 解耦：你可以保留熟悉的 Agent 工作流，同时选择官方模型、OpenAI-compatible 服务、本地模型或企业网关。

但自由度也意味着责任更多。先记录版本，用 opencode debug config 验证最终配置；再在隔离项目跑一个能自动验证的最小任务；确认权限、分享和费用边界后，才进入真实仓库。

本文的最小任务证明 OpenCode 1.18.18 能完成读取、单行修改和测试闭环，也证明模型目录可能与实际可用状态不一致。成功结果和失败边界一起保留，才是比“安装成功截图”更有用的实测。

常见问题

OpenCode 免费吗？

OpenCode 客户端是开源项目，并提供部分免费模型入口，但你连接的商业模型通常按各 Provider 的规则计费。免费模型名称、额度和可用性会变化。

OpenCode 支持 Windows 吗？

支持。官方提供 Scoop、Chocolatey 和桌面端方案，同时建议重度终端用户优先考虑 WSL。

OpenCode 可以接 GLM 吗？

可以通过 Custom Provider 配置 OpenAI-compatible 接口。本文配置已在 1.18.18 中解析通过，但没有使用真实 GLM Key 完成调用，因此仍需你用自己的账号执行最小请求验证。

opencode.json 应该放在哪里？

团队项目规则放在仓库根目录的 opencode.json；个人默认配置放在 ~/.config/opencode/opencode.json。密钥不要提交到项目文件。

权限设置可以当安全沙箱吗？

不可以。官方把 Permission 定义为交互控制，不是真正隔离。不可信任务应放入 Docker 或虚拟机。

为什么模型列表中有模型，实际却不能运行？

模型目录、客户端版本、账号权限和服务端状态可能不同。更新客户端、检查 Provider 与模型 ID，并执行真实最小任务；不要只以列表结果判定可用。