企业官网建设流程全解析

OpenCode 这个名字，最近在 AI 编程圈子的出现频率肉眼可见地在涨。有人拿它和 Codex 比，有人把它当 Claude Code 的平替，还有人单纯想找一个能装在自己电脑上、模型随便换的开源方案。我前后把 OpenCode 从安装到深度使用整个流程走了一遍，这篇就把 OpenCode 的安装与使用经验一次性讲清楚，包括几个特别容易卡住新人的报错、免费额度的真实规则、以及很多人忽略的 Skill 扩展机制。

简单交代一下背景：OpenCode 是一个运行在终端里的开源 AI 编码代理，你给它一句自然语言指令，它能自己读项目代码、修改文件、执行命令，中途遇到报错还会尝试自己修。它适合三类人：第一类是常年在终端里工作的开发者，习惯用 Vim/Neovim 或纯命令行工作流；第二类是想要一个不锁定特定 IDE、底层模型可以自由切换的 AI 编程工具；第三类是喜欢把重复性工作提炼成固定流程的人，OpenCode 的 Skill 机制能帮你把这些流程沉淀成可复用的能力。

1. OpenCode 到底是什么——先和 Cursor、Codex 划清边界

1.1 一个跑在终端里的 AI 代理，而不是又一个 AI 编辑器

很多人第一次用 OpenCode 会下意识找编辑器窗口，然后发现它根本没有传统意义的图形界面。它的工作场景就是终端：你在命令行里敲opencode回车，进入一个类似聊天框的交互界面，底部输入提示词，顶部是模型给出的回复，模型能发起文件读写、命令执行等操作。

这个定位和 Cursor 完全不同。Cursor 是"给编辑器加 AI"，核心是补全、问答、在编辑器里内嵌一个对话面板；OpenCode 是"给终端加 AI 代理"，核心是你把一项任务整体交给它，它自己规划步骤并动手执行。打个不那么准确的比方，Cursor 更像一个随身副驾，OpenCode 更像一个你说完需求就自己去干活、干完活回来找你汇报的临时工。

和 Codex 相比，OpenCode 最大的差异点在于开源和模型无关。Codex 本身就是绑定 OpenAI 模型的，想换 Claude 或本地模型，基本绕不开魔改；OpenCode 这边的 Provider 配置非常灵活，Anthropic、OpenAI、本地 Ollama、所有兼容 OpenAI 协议的网关都能接。这也是它在开源社区里能快速起量的一个重要原因。

1.2 它凭什么值得装

从实操角度看，OpenCode 有几个很抓人的点：

• 开源可审计：代码全部在 GitHub 上，安装之后本地跑什么、数据写到哪个目录，全都能查，不存在"私有闭源工具偷偷上传整个仓库"的顾虑。
• 模型无关：同一个客户端，今天用 Claude 干活，明天想试试 Codex 的风味，改配置就行，不需要迁移工作流。
• 原生终端体验：对熟悉命令行的人来说，它的效率上限非常高。你可以用opencode run "修复某个测试用例"这种非交互方式，把它接进自己的脚本或 CI 流程里，这一点是图形界面工具很难做到的。
• 可扩展的 Skill 机制：把团队的代码规范、审查流程、发版检查清单，封装成一个个 Skill，让模型在特定场景下自动套用这些规则。

这些特性叠加起来，决定了它不是一个"玩具"，而是能真正嵌入日常工作流的生产力工具。

1.3 归档风波与社区继任

提到 OpenCode，避不开那个让不少人困惑过的问题：项目归档后去哪了？大概在 2025 年年中，原维护团队把最初的 OpenCode 仓库标记为归档，很多关注者一度以为项目凉了。实际的情况是，社区在opencode-ai这个账号下继续接过了维护工作，新仓库保持了非常高的活跃度，版本更新速度和 issue 响应都比想象中好。

这个背景对使用者有一个直接影响：你在网上搜资料时，会看到大量基于旧仓库的教程，里面提到的安装命令、配置路径很可能已经过时。建议以官网 opencode.ai 和 GitHub 上opencode-ai/opencode仓库的 README 为准，遇到教程和官方文档冲突时，优先信官方文档。

2. 安装全流程：命令行、桌面端、VSCode 插件三条路线

2.1 前置环境：先把 Node.js 准备好

OpenCode 的 CLI 版本本质是一个 Node.js 应用，安装前需要本机有可用的 Node.js 环境。我这里用的是 Node.js 20 LTS，OpenCode 对 Node 版本的要求不算苛刻，但建议至少 18 以上，太老的版本容易在安装依赖时出问题。

检查本机 Node 版本的命令：

node -v npm -v

如果node命令不存在，先去 Node 官网下载 LTS 版本安装。这里有一个很常见的坑：直接用系统包管理器装的 Node，版本可能很旧，导致 OpenCode 装上之后一启动就报语法错误。我自己在 Ubuntu 上遇到过一次，后来改用 nvm 管理 Node 版本才消停。

提示：如果你之前用sudo npm install -g装包时遇到过 EACCES 权限错误，说明你的 npm 全局目录权限有问题，建议先装好 nvm，再用 nvm 来管理 Node，而不是硬着头皮用 sudo 全局装包。

2.2 两种主流安装方式：官方脚本与 npm

OpenCode 官网提供了一键安装脚本，也支持 npm 全局安装，两种方式我都实测过：

# 方式一：官方安装脚本（macOS / Linux） curl -fsSL https://opencode.ai/install | bash # 方式二：npm 全局安装 npm install -g opencode-ai

安装脚本的优点是省事，它会自动把可执行文件放到你的用户目录下并写入 PATH；npm 方式的优点是版本管理直观，以后想升级直接npm update -g opencode-ai就行。我个人最终留在 npm 方式，理由是升级链路更统一，也方便用 npx 临时跑某个版本。

安装完成后，命令行里验证一下：

opencode --version

能输出版本号就说明环境基本没问题。如果提示command not found，大概率是 npm 全局 bin 目录没在 PATH 里，定位方式我放在后面的排查章节细说。

2.3 Windows 和 VSCode 插件路线

Windows 用户有两个选择：一是用 WSL 里的 Linux 环境安装，二是直接装桌面版。桌面版是图形化打包好的应用，官方下载页有 Windows 安装包，拿到之后一路下一步即可。安装过程中如果 Windows SmartScreen 弹了"你的组织使用适用于企业的应用控制阻止此应用"这类提示，先确认安装包来源是不是官网，然后在确认安全的情况下选择"仍要运行"。这个拦截其实和 OpenCode 本身没有关系，是 Windows 对未签名应用的默认策略，很多人第一次遇到会误以为是安装包有问题。

VSCode 生态也有对应的 OpenCode 插件，在扩展市场直接搜 "OpenCode" 就能找到。装好之后，左侧活动栏会出现 OpenCode 图标，打开就能在编辑器里直接进入对话。

这里有一个很容易忽略的细节：VSCode 插件本质上还是会调用本机的opencode命令。如果你只装了插件、没装 CLI，打开插件时会报找不到命令。所以正确顺序是：先装好 CLI，再装 VSCode 扩展。插件还会在第一次使用时询问 OpenCode 的可执行文件路径，如果 CLI 不是通过安装脚本装的，建议手动确认路径是否配置正确。

为了方便对比，我把三条安装路线的特点整理如下：

2.4 安装后的第一次启动体验

在前面这些步骤都完成后，进到一个测试项目目录，直接运行：

opencode

第一次启动会做一些初始化，然后进入交互界面。界面底部是一个输入框，顶部是模型回复区。首次使用会让你选择模型 Provider，这个环节很多人会被绕晕，我放在下一章详细讲。

输入/help可以查看内置命令列表，建议第一件事先把这个列表扫一遍，至少记住/models（查看和切换模型）、/init（生成项目全局规则）、/undo（撤销模型最近一次操作）这几个高频命令。

3. 模型接入与免费额度规则：那个报错到底在说什么

3.1 首次启动的模型选择逻辑

OpenCode 的模型不是写死的，而是通过 Provider 机制接入。所谓 Provider，就是"模型服务来源"，可以理解为负责输出回复的后端。官方内置了 Anthropic、OpenAI、OpenCode 免费通道等常见 Provider，同时也支持通过配置 opencode.json 来自定义兼容 OpenAI 协议的网关。

首次启动时，交互界面会引导你选择一个 Provider。如果你没有现成的 API Key，可以直接选 OpenCode 官方的免费通道，也就是界面里标注了 free 字样的模型选项。这个免费通道是 OpenCode 给用户提供的一个入门方案，不需要自己申请各类模型服务的 API Key，在客户端里就能直接发起对话。

3.2 深度拆解 error from provider (console) 这个报错

社区和热搜里非常高频的一条报错是：

error from provider (console): opencode's free tier can only be used from within opencode

这条报错让很多人一头雾水：既然是免费模型，为什么我调不通？问题出在"调用的方式"上。

这个免费额度的设计初衷是限定在 OpenCode 客户端内部使用。OpenCode 的免费通道本质是一个受保护的转发服务，它只接受来自 OpenCode 客户端发起的请求。如果你尝试把这个通道的接口地址或参数扒出来，放到浏览器控制台、Postman、curl 或者其他第三方工具里手动调用，服务端就会返回上面这句报错，直白点说就是：免费额度只能在 opencode 里用，不允许绕过客户端当公共 API 用。

我见过有人把这个 Provider 的配置填到其他编程工具里，想给别的应用白嫖算力，结果同样是这个报错。这其实是一种防滥用手段，不是 OpenCode 出了 bug。

遇到这条报错时，正确的处理思路只有两个：

• 如果你确实想用免费通道，那就老老实实在 OpenCode 客户端内使用，不要把它提取出来搬到别处。
• 如果你想在其他工具里用模型，去申请对应模型服务自己的 API Key，或者跑一个本地模型，不要打 OpenCode 免费通道的主意。

3.3 OpenCode Go 套餐与 Codex 接入

除了免费通道，OpenCode 生态里还有一个付费订阅叫 OpenCode Go。我目前了解到的情况是，它主要解决的是"省去你自己去各个模型厂商单独申请和配置 API Key"的麻烦，订阅之后能在客户端内直接获得包括 Claude、Codex 等更强模型在内的使用通道。对个人开发者来说，这比分别去几个平台注册、充值、管理多个 Key 要省心不少。

接入手感上，开通 OpenCode Go 之后，模型的 Provider 列表里会多出对应选项，选中就能用，不需要自己往配置文件里写复杂参数。不过这个套餐的具体定价、模型列表变动比较频繁，我的建议是以上官网最新的订阅页说明为准，别轻信二手信息。

这里也要多说一句：Codex 的名字最近在热词里出现频率很高，很多人问 OpenCode 能不能接 Codex。答案是可以的。不管是通过 OpenCode Go 的通道，还是你自己配置 OpenAI 相关的 Provider，都能在 OpenCode 客户端里获得使用 Codex 系列模型的能力。这和"把 Codex 命令行工具单独装一套"是两条不同路径，前者是把模型接到 OpenCode 里用，后者是直接用 Codex 自己的 CLI，各有各的适用场景。

3.4 免费替代方案：本地模型与兼容网关

如果你既不想订阅，又不想用免费通道的客户端绑定限制，本地模型是另一个可靠方向。OpenCode 支持通过 Ollama 接入本地模型，配置方式是在 opencode.json 里声明一个本地 Provider：

{ "$schema": "https://opencode.ai/config.json", "provider": { "ollama": { "npm": "@ai-sdk/ollama", "name": "Ollama", "options": { "baseURL": "http://localhost:11434/v1" }, "models": { "qwen2.5-coder:14b": { "name": "Qwen2.5 Coder 14b" } } } } }

本地模型的好处是数据完全不出机器，隐私边界清晰；代价是模型能力相比云端旗舰模型有明显差距，复杂重构类任务会吃力。我现在的用法是：日常简单问答和低风险任务走本地模型，真正要动大手术的重构任务再切到云端强模型。

4. 核心使用路径：从一句提示到一次可靠的代码改动

4.1 交互式会话与任务回滚

安装配置好之后，日常使用的主场景是在项目目录下运行opencode，进入交互式会话。你输入一个任务描述，比如"帮我看看这个项目的依赖版本有什么问题"，模型会自己开始读代码、分析，并在需要时向你发起操作请求。

这里要重点提一下操作确认机制。OpenCode 的模型在执行文件写入、命令运行时，会请求你的授权，你需要在界面上确认。这个过程不要一路无脑回车，尤其是模型准备执行命令之前，看一眼它要跑什么。

如果模型做了你不满意的改动，/undo命令能回滚最近一次操作。我一开始没太重视这个命令，直到有一次让模型批量改文件，它改完之后我发现 import 顺序全乱了，一个/undo全撤回来，这才发现这个功能有多救命。与之配套的还有/redo重做被撤销的操作，以及/compact压缩上下文——当对话太长、模型开始"忘记"前面内容时，用 compact 能缓解。

4.2 权限控制：防止模型执行危险操作

OpenCode 的权限模型是"模型发起，用户确认"，但每个操作都弹确认框也会烦。它允许你对不同操作设置策略，比如"读取文件允许","编辑文件允许","执行命令每次都询问"。我个人的建议是：执行命令这个动作保持"每次询问"，至少在你不完全信任项目的环境下这样做。

有一次模型在帮我排查测试失败时，想跑一条rm -rf相关命令，虽然它的意图是清理构建产物，但这种命令一旦路径拼接出错后果很严重。我当时因为正忙着看另一个文件，差点直接按了确认，反应过来之后立刻取消了。从那以后我就把命令执行权限调成了"每次询问"。你可能觉得这是小事，等真出一次事就明白了。

4.3 非交互模式：把 OpenCode 接进脚本

OpenCode 最有别于图形工具的地方，是它的非交互模式：

opencode run "检查当前分支上所有改动，找出潜在的空指针风险"

opencode run会直接执行任务并退出，不需要你进入交互界面。这意味着你可以把它写进 shell 脚本、接到 Git hooks 里、甚至放进 CI 流程。比如我自己的一个习惯是：用一条命令让模型对 git 暂存区的改动做一次快速 review，输出结论，然后再考虑要不要把建议应用到代码里。

这种"先给结论、再动手改"的模式，相当于给命令行加了一个 AI 审查员，而且完全不影响原来的人工代码流程。

4.4 让模型长期记住项目规则：/init 与 AGENTS.md

很多人用了很久 OpenCode，可能都没发现/init命令的价值。/init会在项目目录下生成一份AGENTS.md文件，你可以把项目的架构约定、代码风格、常用命令写进去。之后模型每次在这个项目里工作时，都会自动读取这份文件，相当于一个"项目入职手册"。

我接手一个老项目时，会花 10 分钟把项目启动命令、测试命令、目录结构说明、命名规则写进AGENTS.md，之后模型的所有操作都会更贴合项目实际，而不是给出泛泛的、不符合项目约定的建议。这个习惯值得刻意养成，它对提升任务成功率非常明显。

5. Skill 机制：把重复劳动封装成可复用的能力

5.1 Skill 是怎么工作的

Skill 是 OpenCode 的扩展体系，你可以把它理解成"给模型预置的一套专业流程"。一个 Skill 本质上是一个包含说明文档的目录，说明文档里写清楚"当用户触发这个 Skill 时，模型应当按什么步骤做什么事"。维基百科式的定义不重要，重要的是它能解决什么问题：

• 你希望模型每次做代码审查时都按团队的 Checklist 来，而不是随心所欲地看。
• 你希望模型每次发版前都自动检查版本号、更新日志、依赖锁定文件。
• 你希望模型在写提交信息时统一使用 Conventional Commits 规范。

这些都能通过 Skill 固化下来。第一次配置需要花点时间，但配置一次之后，团队每个人都能复用同一套规则，产出质量稳定得多。

5.2 Skill 的存放位置与安装现成 Skill

OpenCode 会从固定的目录读取 Skill，常用的是全局 Skill 目录和项目级 Skill 目录：

• 全局：~/.config/opencode/skills/
• 项目级：<项目根目录>/.opencode/skills/

每个 Skill 是一个子目录，目录里必须有一个SKILL.md文件，这个文件是 Skill 的核心。找到需要的 Skill 后，把整个目录放到上面两个路径之一即可。安装完成后，在交互界面里输入/skills能查看当前所有可用的 Skill。

5.3 手写一个最简单的 Skill

自己写一个 Skill 一点都不神秘，我来演示一个最简的"代码审查"Skill：

目录结构：

~/.config/opencode/skills/code-review/ └── SKILL.md

SKILL.md内容：

--- name: code-review description: 对当前分支相对主分支的所有改动进行代码审查，按固定清单输出结果。 --- 当用户请求进行代码审查时，请严格按照以下步骤执行： 1. 使用 git diff 获取当前分支相对主分支的改动。 2. 按下面的清单逐项检查改动，不要遗漏： - 是否存在明显的前端显示问题 - 是否缺少必要的错误处理 - 是否存在调试遗留代码 - 命名是否符合项目约定 - 是否引入了不必要的依赖 3. 输出格式：先给总体结论（通过 / 不通过 / 需要修改），再按严重程度列出问题清单，每个问题必须给出文件路径和行号。 4. 除非用户明确要求，否则不要直接修改代码，只输出审查报告。

这里的 YAML frontmatter 部分定义了 Skill 的名称和描述，正文则是给模型的完整指令。保存之后，同一个会话里新发起的请求如果匹配到这段描述，模型就会自动激活这个流程。

Skill 的日志输出能力也很实用。比如我写过一个小 Skill，要求模型每次完成任务后用中文输出变更摘要和建议的测试范围，这让团队在多人协同时能快速知道 AI 做了什么、下一步该人工做什么。封装重复事项这件事，一旦开始就停不下来，因为边际成本太低了。

6. 配置、数据安全与高频问题排查

6.1 配置文件与备份

OpenCode 的全局配置文件在~/.config/opencode/opencode.json（Windows 下一般是%USERPROFILE%\.config\opencode\opencode.json）。模型列表、Provider 参数、界面主题、API Key 信息都存在这里面。

一个很实用的迁移经验：换新电脑时，只需要备份这个配置目录和会话数据目录，恢复后 OpenCode 的模型配置、历史会话就都回来了。如果你也配置了 Skill，记得把skills目录一起打包。

备份命令示例：

tar -czf opencode-backup.tar.gz ~/.config/opencode ~/.local/share/opencode

我习惯每两周备份一次，放在自己的备份目录里，虽然不是天天变化，但真到换机或重装系统时能省大量重新配置的时间。

6.2 数据安全：本地能控制什么，云端会发送什么

OpenCode 的数据安全边界，是所有认真用它做正经项目的人都会关心的点。需要区分两种情况：

• 配置、会话记录、日志、Skill 文件：这些默认存储在本地目录，由你自己掌握。
• 模型请求内容：当你使用云端模型（Anthropic、OpenAI、OpenCode 免费通道等）时，你的提问和代码片段会被发送到对应模型服务商进行处理，这是所有云端 AI 工具的共同特性，不是 OpenCode 特有的风险。

所以，如果你的项目涉及核心商业代码、客户隐私数据，或者处于安全合规要求很高的环境里，建议优先使用本地模型或私有化网关。如果你用云端模型，至少要了解你的数据会流向哪里，不要在一个涉及机密的仓库里随意使用任何云端 AI 工具。

OpenCode 本身也有一些可以关闭的遥测选项，在配置里能找到对应开关，在意隐私的可以主动关掉。

6.3 高频问题排查清单

我把实际使用中遇到过的和社区里高频出现的问题整理成一个清单，方便你直接对照解决：

最后分享一个我自己的使用习惯。我每周五下午会固定让 OpenCode 做一次收尾：第一步，opencode run "git diff 主分支，总结这一周的所有改动要点"，输出一周工作摘要；第二步，让它跑一遍我项目的测试命令，把失败用例列出来。整个过程都是只读和低风险操作，既不会让模型乱改代码，又能快速掌握项目全貌。如果你想把 OpenCode 推荐给团队，我也建议从这类低风险、只读的任务开始，让同事先感受到效率提升，再逐步放开文件编辑和命令执行的权限。这个节奏比一上来就让它做大规模重构要稳妥得多。