企业官网建设流程全解析

最近半个月，已经有好几个原本死守Cursor的朋友跑来问我同一个问题：“OpenCode到底怎么装、怎么用？网上教程怎么说的都不一样？”这也难怪，OpenCode这半年迭代太快了，光是安装方式就换了好几轮，再加上它默认跑在终端里，很多人第一眼看到黑乎乎的界面就劝退了。

先把结论放这：OpenCode是一个开源的AI编程工具，它不只是一个补全代码的插件，而是能理解整个项目、自己制定计划、自己改代码、自己跑命令的AI结对编程助手。它适合三类人：一是本来就习惯在终端里工作的人，二是想把AI编码的配置和日志都握在自己手里的人，三是不想在编辑器里塞一堆插件、想要一个轻量但强大的AI工作流的人。

这篇文章不是官方文档的翻译，而是我从安装到日常使用、从免费额度到编辑器集成的完整实操记录。文里会特别讲几个网上很少有人解释清楚的地方：OpenCode的免费模型额度为什么会报错、Skills技能到底怎么装怎么用、局域网serve模式怎么安全地跑，以及VS Code/Cursor里搜不到插件时的排查思路。照着走一遍，你基本就能把OpenCode用起来了。

1. OpenCode是什么：一个终端里的AI编程搭档

1.1 为什么大家都在从GUI工具转向终端AI

先说个现象。Cursor、Copilot这些工具解决的是“AI辅助写代码”，但它们的形态决定了你只能跟着IDE走：打开项目、右键、触发面板。OpenCode走的是另一条路——它本身就是一个运行在终端里的Agent，你给它一个目标，它能自己去读文件、跑测试、改完代码告诉你结果。

我用它做了一段时间之后最大的感受是：OpenCode更像是一个“同事”，而不是一个“输入法”。比如你丢给它一个从来没见过的仓库，它会先给你梳理目录结构、找到入口文件、解释核心模块怎么串起来的；你让它改一个接口的返回结构，它会自己搜到所有调用方，改完跑一遍类型检查。这些事情如果靠传统IDE插件，得一步步聊天、点应用、等结果。

所以说，OpenCode代表的是一种“AI作为执行者”的工作方式。它不负责给你一个漂亮的编辑器界面，而是负责真正把事情做完。

1.2 它和Cursor、Copilot到底有什么本质区别

很多人问OpenCode能不能完全替代Cursor，我的看法是看场景。

从能力边界来看：

• Cursor的本质是“带AI能力的编辑器”，适合你一边看代码一边让AI帮你补全、解释、小范围修改，你能实时看到diff。
• Copilot的本质是“代码补全工具”，擅长在光标处给你下一行，做跨文件重构就比较吃力。
• OpenCode的本质是“终端里的编程Agent”，它能自己规划任务、批量改文件、执行命令，但它的交互方式是通过对话而不是通过鼠标操作编辑器。

所以如果你是重度依赖可视化diff、需要精细控制每一处改动的人，OpenCode适合作为第二工具，和VS Code扩展配合使用；如果你更看重“把任务丢给AI去执行”，OpenCode的Agent模式会给你完全不一样的体验。

1.3 版本迭代太快，网上教程经常对不上号

搜“OpenCode安装”的时候，你会发现教程特别乱，有些让你用npx opencode，有些让你下载二进制，有些又说GitHub仓库已经归档了。这些其实都和它的版本演进有关。

OpenCode原来的GitHub仓库有一段时间确实被作者归档了，原因是作者在重构一个全新的版本（也就是很多人说的OpenCode v2 / 2.0）。重构之后的架构变化很大，安装包名、配置文件、命令参数都做过调整。所以你看到“归档后去哪了”这种疑问，说的是旧仓库不再更新，新项目换了名字或者换了发布方式继续维护。

实操上记住一点：现在装OpenCode，优先看官方文档opencode.ai/docs，不要拿一年前的教程硬套。如果你运行opencode --version看到的是2.x，说明你用的是新版，网上那些基于旧版的配置方式可能就不适用了。

2. 安装OpenCode：跨平台实操与踩坑记录

2.1 最省事的npm全局安装

先说我个人最推荐的方式：npm全局安装。

在终端执行：

npm install -g opencode-ai

装完检查：

opencode --version

这里有几个容易踩的坑。

第一个是npm包名。早期有些教程写的是npm install -g opencode，实际上opencode这个包名在npm上已经被其他项目占用了，官方现在发布的包名是opencode-ai。你要是装了opencode，执行opencode命令时大概率会报错或者起了一个完全无关的东西。

第二个是Node.js版本。OpenCode要求Node.js 18以上，建议用18 LTS或20 LTS。你可以用node -v看一下，如果版本太老，先升级Node再装，不然安装过程中容易出一些奇怪的编译报错。

第三个是全局bin目录的PATH问题。这个在Windows上特别常见，装完后终端告诉你opencode不是内部或外部命令，但npm install明明成功了。这种情况一般是npm全局bin目录不在PATH里，后面我会专门讲怎么修。

2.2 Linux服务器上怎么装

如果你要把OpenCode装到一台Linux服务器或者开发容器里，有两个选择。

第一个是继续用npm：

npm install -g opencode-ai

前提是服务器上有Node.js。如果是Ubuntu/Debian，建议用nvm装Node而不是直接用apt的旧版本，因为apt源里的Node经常太老。

第二个选择是直接下载官方编译好的二进制：

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

这个脚本会帮你下载对应平台的二进制并放到可执行路径下。装完同样用opencode --version验证。

在服务器上我额外提醒一句：OpenCode的TUI界面依赖终端渲染能力，如果你是通过SSH连接服务器，请确保你的SSH客户端支持颜色和光标控制（比如iTerm2、Windows Terminal、GNOME Terminal都没问题）。如果用的是很老的终端模拟器，TUI可能会有显示错乱，但不影响命令行模式使用。

2.3 Windows PowerShell安装与PATH问题

Windows上装OpenCode，大家会搜到“opencode powershell”或者类似的关键词，实际上就是在PowerShell里执行npm安装。

npm install -g opencode-ai

如果装完之后执行opencode报“无法识别”，按下面步骤排查：

先看npm全局bin目录在哪：

npm config get prefix

比如输出是C:\Users\你的用户名\AppData\Roaming\npm，那这个目录就是要加入PATH的。把该目录加到系统环境变量Path里，然后重开一个新的PowerShell窗口，问题基本就解决了。

另一个Windows上常见的坑是TUI界面乱码、光标乱跳。这不是OpenCode的毛病，而是老版cmd.exe在ANSI转义序列支持上有缺失。解决办法很简单：用Windows Terminal来跑OpenCode，在Windows Terminal里基本不会遇到渲染问题。字体方面建议用MesloLGS NF或者Cascadia Code，图标和边框渲染会好看很多。

2.4 安装后的第一轮自检

装完别急着操作，先花30秒做三个检查：

1. 版本号：opencode --version，确认是2.x以上的新版本。
2. 帮助信息：opencode --help，看一下当前版本支持哪些子命令。
3. 启动探路：直接输入opencode回车，能看到TUI界面就算成功。

如果TUI能出来但界面是空白的，多半是终端尺寸设置得太小，OpenCode的TUI界面需要一定的宽度和高度才能正常渲染，把终端窗口拉大一点再试。

3. 登录与模型配置：从免费额度到OpenCode Go

3.1 先搞明白：OpenCode本身不生产模型

OpenCode不是模型服务商。它更像一个“模型路由器”，把你输入的指令和项目上下文发送给你选择的模型服务商，再把模型的回复拿回来执行。

这意味着，在你真正开始用之前，必须先解决模型从哪来的问题。OpenCode提供了两种方式：

• 使用OpenCode官方账号的免费或订阅额度，很多热词里提到的OpenCode Go就属于这一类。
• 自己配置第三方模型的API Key，比如Anthropic Claude、OpenAI、Google Gemini，或者本地模型服务（Ollama等）。

这两种方式各有适用场景。只想快速体验，用官方账号的免费额度；长期正经干活，建议自己配API Key，或者订阅OpenCode Go。它们之间的差异我放在下面这张表里：

3.2 登录OpenCode账号：opencode auth login

第一次启动OpenCode后，推荐先登录官方账号。在终端里直接执行：

opencode auth login

命令会输出一个链接，让你在浏览器里打开并登录OpenCode的账户系统，授权之后你会拿到一串密钥，把它粘贴回终端，登录就算完成了。

登录的意义在于：你可以使用OpenCode账号体系下的免费模型额度，同时后面订阅OpenCode Go、同步配置都会方便很多。

如果你不想登录，也可以直接配置第三方API Key。执行opencode auth login后，按照交互提示选择对应的模型服务商并填入Key。或者更直接一点，在系统环境变量里设置，比如ANTHROPIC_API_KEY、OPENAI_API_KEY，OpenCode在启动时会自动读取。

3.3 免费额度报错的完整链路排查

接下来这句话请重点看，因为它是网上问得最多的一个问题。

报错原文大概是：

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

这个报错的意思是：“console这个provider提供的免费额度，只能在OpenCode内部使用。”翻译成大白话就是：你想用官方给的免费模型，但你的请求不是从OpenCode客户端发出去的，服务端不认账。

我排查这个报错时梳理过几条路径，你按照顺序排除：

1. 确认你是不是把console provider的配置抄到了别的AI客户端里。因为OpenCode的免费额度本质上和你的OpenCode会话绑定，如果你在别的工具里配了同样的provider地址和密钥，很容易触发这个错误。
2. 确认你的登录态是否正常。重新执行opencode auth login，再跑opencode试试。
3. 如果你是通过OpenCode的serve模式给局域网内其他设备提供接口，请确保对方请求时使用的鉴权信息和客户端标识一致，必要时在serve端配置正确的访问令牌，而不是依赖默认的免费通道。
4. 如果以上都排除了，最省事的办法就是不用免费额度，换成自己的API Key或者订阅OpenCode Go，这类报错就不会再出现。

实际上这个报错大部分情况是第1种和第3种——免费额度是OpenCode给自家客户端用户的福利，你把它当通用接口用，自然会被拦。

3.4 OpenCode Go：订阅、套餐与接入Codex模型

再聊OpenCode Go。简单说，OpenCode Go是OpenCode官方推出的订阅服务，用一个相对合算的价格，在OpenCode客户端里使用多个主流模型，而不必分别去各个模型厂商充值和配置Key。

订阅之后，你在OpenCode的模型列表里就能看到Go套餐包含的模型选项，比如接入Codex模型等。这里的“接入”并不复杂，就是选模型时直接选对应的Go模型，不需要单独去模型厂商控制台创建Key。

操作流程一般是：

1. 在OpenCode的配置或设置里找到Go相关入口，完成订阅绑定。
2. 订阅完成后，在TUI的模型切换列表里出现带Go标识的模型。
3. 选中目标模型，开始对话。

需要提醒的是，Go套餐的具体包含模型、配额和计费规则会调整，建议以官方网站的说明为准。不要看到一篇老教程说“Go包含XX模型”就以为永远不变，订阅前花一分钟看一下条款。

4. 第一次运行：TUI界面的核心操作与Agent工作流

4.1 启动、对话、切换模型

在终端里直接执行：

opencode

就进入了OpenCode的TUI主界面。底部有一个输入框，直接输入自然语言指令，回车发送。输入框内换行用Shift+Enter，如果你写了一大段指令需要多行，可以用这个组合。

交互过程中最常用的几个斜杠命令：

• /models：打开模型切换列表，上下键选择，回车确认。
• /session：管理会话，可以新建、切换、删除。
• /agents：查看和切换不同的Agent模式。
• /help：查看当前版本支持的命令列表。
• /quit：退出OpenCode。

刚上手的时候很多人不知道Esc键的用途。Esc在OpenCode里不是退出，而是打断当前AI正在执行的操作。如果模型答非所问或者陷入了循环，按Esc可以中断，重新组织语言再下达指令。

4.2 Agent模式是怎么“自己干活”的

OpenCode区别于普通聊天的核心是Agent模式。你给它一个任务，它不会只回你一段代码就算完，而是会：

1. 分析任务：理解你要什么，判断涉及哪些文件。
2. 读取上下文：把相关文件读进来，甚至用工具搜索代码里的引用关系。
3. 制定计划：告诉你要分几步做。
4. 动手修改：直接编辑文件。
5. 执行验证：如果任务里涉及命令（比如跑测试、跑构建），它会尝试执行并把输出反馈给你。
6. 调整迭代：如果输出不对，它会自己改，直到通过或放弃。

我举一个实际例子。我给它下达：“把项目中所有用fetch请求/api/v1/users的地方改成使用/api/v2/users，并加上超时处理。”它先会搜索找出所有fetch调用，然后逐个文件修改，改完跑到TypeScript编译，编译报错它会再看一眼是不是漏了类型定义，最后给我一个总结。这个过程中我能看到它每步在做什么，随时可以按Esc介入。

这种“干活式AI”的上手成本比传统聊天高一点，但用顺之后，你会发现自己越来越少去手动搜索、手工改文件了。

4.3 Skills技能：给AI预置一套工作说明书

“opencode skills”是最近搜索量很大的关键词，原因在于它是OpenCode一个非常提升效率的特性。

简单理解：Skill是一段结构化的指令包，告诉AI“接到这类任务时，你应该按照什么流程来做”。你可以把它想象成给新同事写的一本工作手册。

安装官方或社区发布的skill，命令类似：

opencode skills add <skill-name>

也可以自己写一个skill放在项目的.opencode/skills目录下。一个skill通常包含一个SKILL.md文件，里面写清楚触发条件、执行步骤、注意事项。

举个最简单的例子，我写了一个“code-review”的skill，SKILL.md里就写了三步：先读diff，再按性能、安全、可维护性三个维度给意见，最后按严重程度分级输出。之后我在对话里提到“用code review skill看一下这次改动”，它就会照着这套流程执行，而不是自由发挥。

自定义skill是OpenCode拉开体验差距的地方。团队里可以把代码规范、提交信息规范、部署检查清单都做成skill，新成员上手速度会明显加快。

4.4 会话管理、继续对话与项目配置

OpenCode会把会话历史存在本地。重启终端后，你可以用下面命令恢复最近的会话：

opencode --continue

这样上一轮对话的上下文还在，不用重新介绍项目背景。

项目级的配置放在opencode.json里。启动OpenCode时它会读取当前目录下的这个文件，比如你可以在这里指定默认模型、provider、自定义指令、忽略规则。一个最小示例：

{ "$schema": "https://opencode.ai/config.json", "model": "claude-sonnet-4", "provider": { "anthropic": { "apiKey": "{env:ANTHROPIC_API_KEY}" } } }

需要说明的是，不同版本schema字段会有变化，这是我实际使用的写法示例，具体字段应以你本机版本生成的schema为准。配置文件的优势是可迁移、可纳入版本管理、可和团队共享，比在GUI工具里点来点去要透明很多。

5. 编辑器集成：VS Code、JetBrains与桌面版

5.1 VS Code插件安装与“搜不到扩展”的排查

OpenCode官方提供了VS Code扩展，安装后在编辑器里可以打开一个侧边栏，方便在写代码的同时调用OpenCode能力。

在VS Code扩展市场直接搜“OpenCode”，一般第一个就是官方扩展，点击安装即可。

如果你搜不到，几个排查方向：

1. 确认扩展市场源是否正常。有些用户把扩展市场切换到了第三方镜像，导致搜索索引不全，切回官方市场源再看一次。
2. 直接在OpenCode官网的文档页面找到VS Code扩展的安装入口，浏览器会调起VS Code进行安装，或者下载对应的vsix文件，然后在VS Code里通过“从VSIX安装”的方式手动安装。
3. 如果你用的是Cursor，注意Cursor的扩展市场比VS Code小很多，不一定能搜到OpenCode插件。“cursor的扩展搜不到opencode”这个问题，最直接的解法是去OpenCode官网下载vsix，然后在Cursor里以本地安装的方式装进去，或者干脆用OpenCode桌面版。

VS Code扩展装好之后，需要确保opencode命令在你的PATH中，否则扩展可能找不到可执行文件。

5.2 JetBrains系列（IDEA、PyCharm）

JetBrains系用户也不用担心，OpenCode官方同样发布了IDE插件。

安装路径：打开IDEA或PyCharm，进入Settings -> Plugins，在Marketplace搜索OpenCode，找到后安装并重启IDE。

装好后需要在设置里配置opencode可执行文件的路径。如果你是npm全局安装的，Linux/macOS下一般就是which opencode的输出结果；Windows下是npm的全局bin目录里的opencode.cmd。把路径填进插件设置，插件就能调用OpenCode了。

用起来和在VS Code里类似，侧边栏可以打开对话窗口，选中代码后可以直接让AI解释、修改，或者要求生成单测。

5.3 桌面版：不想碰终端的人的福利

如果你觉得TUI实在不习惯，或者团队里有非技术背景的同学也要用，直接上OpenCode桌面版。

桌面版本质上是把终端里的OpenCode包装成了一个图形界面应用，内置了登录、模型配置、会话管理面板，打开即用。官网上提供Windows、macOS、Linux三个平台的安装包，下载安装后按引导登录就行。

我的建议是：个人日常开发用TUI足够，给同事推荐或者轻量使用时用桌面版更友好。两边共享同一套账号和配置逻辑，不存在数据孤岛问题。

6. 服务化与数据安全：局域网共享、存储与隐私

6.1 opencode serve：把AI能力变成局域网接口

如果你的电脑性能很好，或者你希望同一个模型配置给多台设备共用，可以用serve模式把OpenCode作为一个本地或局域网服务跑起来。

基本用法：

opencode serve --hostname 0.0.0.0 --port 3456

执行后OpenCode会在这个端口上提供HTTP接口，局域网的其它设备就可以通过这个接口发送请求。一些团队会把OpenCode跑在一台专用机器上，其他人不安装任何AI工具，直接通过接口来调用。

但这里我必须强调安全：把服务绑到0.0.0.0意味着局域网内所有设备都能访问你的端口。如果你没有配置鉴权，其他人可以免费使用你的额度，更严重的是，请求内容会暴露在网络上。实际使用至少要做到：

• 配置访问令牌，让客户端请求时携带正确的凭证；
• 只在可信的局域网内开放，不要随意暴露到公网；
• 定期查看OpenCode的日志，监控异常调用。

6.2 数据存在哪、哪些会发给模型

“opencode数据安全”是很多人关心的问题。OpenCode作为本地优先的开源工具，会话历史、配置、日志默认都存储在本地目录下面。具体路径因操作系统而异，一般是在用户主目录下的.opencode或~/.local/share/opencode这类位置。

但要注意一个事实：只要你选择的是云端模型，你的指令、代码片段、AI的回复就会作为请求内容发送给对应的模型服务商。这不是OpenCode独有的问题，所有AI编程工具都一样。如果项目代码敏感，你有三条路可以走：

• 配置本地模型（比如Ollama），让请求不出内网；
• 在上传前用ignore规则排除敏感文件，OpenCode配置里可以设置不纳入上下文的目录或文件；
• 不做实时联网操作，只把OpenCode当作代码分析工具的辅助。

开源的优势在于，你可以自己去读源码、看它到底把数据发到哪，也可以自己搭建服务层，掌握完整的数据链路。

6.3 配置层面的隐私保护实践

我自己的做法是在opencode.json里维护一份忽略列表，把.env、密钥文件、生成目录都排除在外。这样模型请求里不会带上这些内容，减少泄露风险。

同时，尽量不让AI接触生产环境的凭据。哪怕你的模型服务商承诺不存储数据，习惯上也应该遵循最小暴露原则——只给它看跟当前任务相关的代码，而不是整个仓库一把梭。

7. 高频报错排查手册：我从踩坑到脱坑的过程

7.1 command not found：npm装完却找不到命令

这个报错在Windows和Linux上都可能出现。核心原因就是npm的全局bin目录没有加入PATH。

排查命令：

npm config get prefix

取得prefix路径后，把path/to/prefix/bin（Windows上是prefix本身）加入系统PATH，然后重新打开终端。

如果确定PATH没问题，那可能是npm安装时权限不够，导致可执行文件没有正确生成。Linux/macOS下可以用sudo npm install -g opencode-ai重装，或者用nvm管理Node环境后避免权限问题。

7.2 免费额度报错：provider（console）拒绝服务

详细原理前面已经讲过了，这里只给一个排查路线图：

1. 检查你是否把console provider用在非OpenCode客户端里；
2. 重新登录opencode auth login；
3. 检查serve模式下的鉴权配置；
4. 换成自己的API Key或者订阅Go套餐。

这四条按顺序走，九成情况能解决。

7.3 模型请求超时或429限流

用免费额度或者并发任务太多时，容易遇到请求超时、429（Too Many Requests）之类的错误。

我的经验是：如果是临时性限流，等几分钟再试即可；如果是频繁出现，说明你的使用量已经超出了免费额度，继续依赖免费通道没有意义，切换到自己的付费Key或者Go套餐才稳定。

OpenCode通常会在报错信息里告诉你限流的维度，认真读一下报错，比盲目换模型有效。

7.4 TUI界面乱码、按键错乱

Windows老版cmd里跑OpenCode出现乱码和按键错乱，直接换Windows Terminal。macOS的默认Terminal基本没问题，但如果你的终端模拟器太老，也建议换iTerm2或系统自带的Terminal升级版。

另外，如果你在SSH会话里跑OpenCode，建议在远端安装时选择与服务器匹配的终端类型，连接时设置好环境变量TERM=xterm-256color，很多显示问题会自动消失。

TUI界面里按键错乱还有一个常见原因：开启了中文输入法。输入指令前先切到英文输入法，避免命令被自动替换成全角字符。

为了方便以后遇到问题能快速对照，我把这一章提到的报错场景整理一下：

OpenCode这个工具，表面上是一个终端应用，实际上是一整套“把AI变成项目执行者”的思路。我在实际使用里最深的体会是：它真正改变了我的工作流，让我从“写每一行代码”逐渐变成“指挥AI写代码、我负责审查方向”。这个过程需要适应，但一旦跑通，你会发现自己每天能处理的迭代量完全不一样。

最后再分享一个小技巧：如果你打算长期用OpenCode，一定要把opencode.json、skills目录、常用的自定义指令都整理好放进项目的模板仓库里。这样换电脑、换团队、开新项目的时候，只需要几分钟就能把整套AI工作流恢复过来，而不用重新在GUI里点一遍设置。这比记住任何一条具体命令都重要。