企业官网建设流程全解析

最近 opencode 在开发者圈子里讨论度很高，各种终端录屏和博客里频繁出现。我一开始以为又是一个套壳的 Codex CLI，结果装上用了两周之后发现，这个开源项目的思路其实挺不一样。它不绑死某一家模型厂商，官方支持 OpenAI、Anthropic、Gemini、本地 Ollama 等等，而且终端界面、Skills 扩展、Memory 记忆、Agent 自定义这套机制做得比很多同类工具都更开放。这篇文章就围绕我实际安装、配置、接手一个中小型项目的过程，把 opencode 从零到能顺畅跑通的完整路径梳理一遍。

如果你之前用过 Claude Code 或者 Codex CLI，看完这篇可以直接知道 opencode 到底差别在哪；如果你刚接触这类终端 AI 编程工具，照着我的步骤走，也能避免很多我一上来就踩过的坑。

1. opencode 是什么：一个开源的终端 AI 编程 Agent

1.1 它解决什么问题

先聊聊这类工具存在的意义。传统的 AI 编程助手大多以 IDE 插件的形式存在，你选一段代码，它给你补全或者解释，交互模式本质上是“问答式”。opencode 更像一个真正能在终端里干活的智能体，你可以直接让它“把这个模块重构掉”“把测试跑一下然后修复失败用例”，它会自己读取项目文件、修改代码、执行命令，甚至调用浏览器做调试。

它和 Claude Code、Codex CLI 属于同一类产品，核心差异在于 opencode 是开源且厂商中立的。Claude Code 虽然很好用，但默认绑定 Anthropic 的模型；Codex CLI 则是 OpenAI 自家生态。如果你想要在多模型之间自由切换，或者想用本地运行的模型来处理敏感代码，opencode 就提供了一个更灵活的空间。

1.2 和 Codex CLI / Claude Code 的核心差异

我把几个常见的终端 AI 编程工具放到一起对比过，差别主要在下面几个维度：

这个表不是说谁绝对更好，而是说 opencode 的定位更偏向“终端里的瑞士军刀”。它把模型选择权和扩展自由度都交给了用户，代价是刚上手时需要多花一点时间理解配置结构。

1.3 适合谁来用

我个人的判断是，这类工具适合以下三类人：

第一种是日常主力在终端里开发的人，能接受命令行交互，不想开 IDE 或者嫌 IDE 插件太重。第二种是需要在不同模型之间切换的人，比如日常用 Claude 写复杂逻辑、用 GPT-4.1 做代码审查、又偶尔想用本地模型处理私有代码。第三种是喜欢折腾和定制的人，opencode 的配置、Agent、Skills 全是文件化的，配合 Git 可以版本化管理。

如果你完全依赖图形界面，也不想关心任何配置文件，那可能 VSCode 里的 Cline 或者 Cursor 更省心。但如果你愿意花半天时间把工具调顺，后面省下来的时间会非常可观。

2. 安装 opencode：从零到能跑通

2.1 支持哪些安装方式

opencode 的安装方式很全，挑一个你顺手的就可以。官方文档里最常见的是这种一键脚本：

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

如果你用的是 npm，也可以直接用全局安装：

npm install -g opencode-ai

macOS 用户还能走 Homebrew：

brew install sst/tap/opencode

我在公司电脑上用的 npm 方式，在家里的 macOS 上用的 Homebrew，两条路线都很干净。安装完成之后务必确认版本号，否则后面排查问题都不知道从哪找起：

opencode --version

2.2 Windows 上最典型的一个坑

很多 Windows 用户在 PowerShell 里执行 opencode 的时候，会遇到下面这么一大段报错：

opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。请检查名称的拼写，如果包括路径，那么请确保路径正确，然后再试一次。

这基本就是 PATH 环境变量没生效，或者 npm 全局包的安装目录没有加到 PATH 里。解决思路分三步：

第一步，先确认 opencode 到底装没装上。在 PowerShell 里执行：

npm prefix -g

会输出一个全局 Node 包目录路径，类似C:\Users\你的用户名\AppData\Roaming\npm。第二步，打开系统环境变量设置界面，把上面这个路径追加到Path变量里。第三步，完全关闭当前终端窗口，重新打开一个新的 PowerShell 再试一次。

注意：很多人在修改完 PATH 之后没重启终端，或者只开了个新标签页，结果旧环境变量缓存还在，依然报错。建议改完之后彻底退出终端程序再重开一次。

如果你没用 npm，而是用了一把脚本安装，那 opencode 的可执行文件通常会落在~/.opencode/bin这个目录下，同样需要确保这个目录在 PATH 里。在 Linux/macOS 上可以直接加一行到~/.zshrc或~/.bashrc：

export PATH="$HOME/.opencode/bin:$PATH"

2.3 升级与卸载

升级很简单，如果通过 npm 装的：

npm update -g opencode-ai

如果是脚本安装，直接再跑一遍安装命令，它会把旧版本覆盖掉。卸载同理，npm 装的就用 npm 卸载，脚本装的删除~/.opencode目录，再把 PATH 里对应路径去掉即可。

3. 首次启动与基础配置

3.1 第一次运行会发生什么

安装完成后，建议先找一个测试目录，比如~/demo-opencode，执行一下git init，然后再运行opencode。它会拉起一个全屏终端界面，也就是 TUI。第一次进来的时候会引导你配置提供商，你可以选择登录某个模型厂商，或者先跳过，后面用配置文件补上。

TUI 界面本身就是用终端组件做出来的，支持鼠标点击、上下键选择文件、点击 @ 符号引用文件。我用它连续工作三四个小时之后发现，信息密度比 IDE 侧边栏还要高，左边是对话列表，中间是对话内容，底部是输入框，顶部还能看到当前模型和 token 消耗。

3.2 配置模型 API 的三种方式

opencode 的模型配置有三种途径，按优先级从高到低分别是：配置文件、环境变量、登录状态。实际使用时我建议统一用环境和配置文件组合。

环境变量方式最直接，比如你要用 openai 和 anthropic 的模型，在终端里先导出：

export OPENAI_API_KEY="sk-你的key" export ANTHROPIC_API_KEY="sk-ant-你的key"

Windows PowerShell 对应写法是：

$env:OPENAI_API_KEY="sk-你的key"

但每次都要手动导环境变量很烦，我的做法是把这些 key 写到系统环境变量或者 shell 配置里，然后在 opencode.json 中引用。配置文件里引用环境变量的写法是：

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

这种方式的优势非常明显：key 不落盘到配置文件，而且配置文件可以放在 Git 仓库里给团队共用，别人克隆下来只需要配各自的环境变量。

3.3 TUI 里的第一个任务

进入 TUI 之后，最常用的几个交互技巧：

在输入框里输入/help可以查看所有可用命令。/models用来切换当前模型。/agents可以查看和切换预设的 Agent。输入@可以引用项目里的具体文件，opencode 会把文件内容作为上下文发送给模型。你还可以直接输入一段需求，比如：

把 src/utils/format.ts 里的时间格式化函数重构一下，改成支持时区参数，并补充对应测试

opencode 会自动列出需要读取的文件、修改的文件、执行命令，然后一步步完成。每一步操作前都会让你确认，这个确认机制在改代码的时候非常关键，不建议为了省事全局关闭。

3.4 非交互模式：一条命令跑完一个任务

如果你不想进 TUI，opencode 也提供了直接的命令行运行模式：

opencode run "给这个项目添加一个 README.md，内容包括项目简介和启动方式"

还可以指定模型：

opencode run -m anthropic/claude-sonnet-4 "检查所有 TypeScript 文件，找出潜在的 null 引用风险"

这种模式非常适合写 CI 脚本，或者临时快速处理一些小改动。我建议不要用它执行太复杂的多步骤重构，因为非交互模式下它虽然会自动执行命令，但如果中间出错了，你只能在日志里看原因，处理起来没有 TUI 里面直观。

4. 把 opencode 配置成趁手的样子

4.1 全局配置文件的幕后逻辑

opencode 的配置体系是我觉得最值得讲的点。它分全局配置和项目配置两层，全局配置放在~/.config/opencode/opencode.json，项目配置放在当前项目根目录下的opencode.json。两者会合并，项目配置优先级更高。

一个典型配置里可以做的事很多，除了指定 provider 和 model，还可以设置 Agent 的默认行为：

{ "$schema": "https://opencode.ai/config.json", "model": "anthropic/claude-sonnet-4", "agent": { "build": { "description": "负责构建、编译、依赖安装", "mode": "primary", "model": "anthropic/claude-sonnet-4", "temperature": 0.2, "tools": { "write": true, "edit": true, "bash": true, "read": true } } } }

如果你对提示词工程有经验，还可以在 agent 配置里加入prompt字段，写上一段针对该 Agent 的系统指令。这个机制其实就是在给 AI 做“角色设定”，比如让某个 Agent 专门写单元测试、专门做代码评审、专门做性能分析。

4.2 接入本地 Ollama 模型

opencode 支持非常多的 provider，官方云厂商这边 OpenAI、Anthropic、Google、Mistral 都有。这里单独拿出来说 Ollama，是因为本地模型在很多场景下有不可替代的价值：断网可用、敏感代码不出机器、没有按次计费的成本压力。

假设你已经本地起好了 Ollama 并且拉了一个模型，比如llama3.1，那么 opencode.json 里这样配置：

{ "provider": { "ollama": { "npm": "@ai-sdk/ollama", "name": "Ollama", "options": { "baseURL": "http://localhost:11434/api" }, "models": { "llama3.1": { "name": "Llama 3.1 8B" } } } } }

配好之后在 TUI 里用/models，就能看到 Ollama 下的llama3.1这个模型。本地模型的强项是代码补全、简单重构、解释代码，复杂架构设计还是差一些。我自己的用法是：涉及隐私的代码分析交给本地模型，复杂逻辑实现交给云端模型。

提醒：opencode 本身是开源免费的，但它要调用模型的能力，仍然取决于你用哪家模型服务商、是否采用本地模型。官方云模型的计费也是按各家服务商的定价走的，和 opencode 本身无关。

4.3 Skills 扩展：给 Agent 加技能包

Skills 可以说是 opencode 最让我惊艳的部分。简单理解，它是一个“能力插件系统”，把常见的专家知识和操作流程打包成可以在对话里随时调用的技能。

opencode 默认就能加载项目目录下.opencode/skills/或者用户目录下~/.config/opencode/skills/里的技能。每个技能是一个目录，里面有个SKILL.md，格式大概是：

--- name: playwright-debug description: 用 Playwright 复现和诊断前端页面 bug --- 当用户提到页面问题、前端 bug、布局错乱时，使用这个技能定位问题： 1. 先启动开发服务器 2. 用 Playwright 截图并检查控制台报错 3. 复现操作路径，分析 DOM 结构

有了这个 SKILL.md 之后，我在对话里说“这个页面点击按钮没反应”，opencode 就会从描述匹配到 playwright-debug 这个技能，然后按照步骤自己跑浏览器、截图、看 console 报错，而不是只给我一段猜来猜去的代码。

社区里还有一个比较流行的技能包叫 superpowers 或 agent skills，里面默认集成了前端调试、后端排查、数据库分析等一堆技能。安装方法通常是把对应仓库克隆下来，然后把 skills 目录软链到 opencode 的 skills 目录。这一类扩展的生态还在快速变化，建议以官方文档和仓库 README 为准。

4.4 Memory 记忆：让 Agent 记住上下文

另一个实用的功能是 Memory。它解决的是 AI 对话“转身就忘”的毛病。你可以在对话里输入/memory查看和编辑记忆，也可以让 opencode 在合适的时机自动记录关键信息，比如项目使用 monorepo 结构、代码规范要求单引号、测试命令是pnpm test等等。

除了显式记忆，项目根目录下的AGENTS.md文件也承担类似作用。opencode 在处理这个项目的时候会默认读取 AGENTS.md 的内容作为背景上下文。这其实是从 Claude Code 那边的 CLAUDE.md 借鉴过来的机制，但它采用了一个相对通用的文件名，避免把项目绑定在单一工具上。

对我来说，AGENTS.md 是接手新项目时最有价值的文件。我在接手一个不熟悉的仓库时，第一件事就是让 opencode 快速浏览项目结构、启动脚本、关键入口，然后把结论写进 AGENTS.md。这样下次打开，它不需要重新扫一遍就能快速进入状态。

5. 用一个真实项目走一遍完整流程

5.1 接手旧项目时的初始化操作

为了演示 opencode 实际怎么工作，我拿了一个自己很久没碰过的个人开源小项目做测试。这个项目是 TypeScript + Express + React，代码结构比较乱，测试也不全。

我进入项目目录后先手动执行了git init和git status，确保 opencode 能正确感知文件变更。然后运行opencode，在 TUI 里输入：

看一下这个项目的整体结构，梳理出主要模块和入口，写一份 AGENTS.md

它先是读取了 package.json、tsconfig.json、src 目录列表，然后逐个分析了几个核心文件，最后自动生成了 AGENTS.md。整个过程大概两分钟，比我手动看完整个项目节省了很多时间。生成的 AGENTS.md 准确率很高，因为它基于实际文件内容，不是猜的。

5.2 让 Agent 重构核心模块

接着我让它做一件更复杂的事：

把 src/services/userService.ts 里的大函数拆分成多个小函数，保持对外接口不变，并补充单元测试

这个任务如果让工具链不熟练的模型去做，很容易把接口签名改坏。opencode 的处理方式是：先读取原文件、相关调用方、现有测试文件，然后输出一个行动计划，问我要不要执行。确认之后才开始改代码。改完后它自动跑了npm test，发现有一个测试因为 mock 方式不对挂了，又自己修复了 mock 文件，最后所有测试通过。

这个过程中我特别注意到 opencode 的“工具调用”能力。它不是光生成代码就完事，而是真的会去执行命令、看运行结果、再根据结果调整代码，这种“改代码—跑测试—修问题”的闭环很关键。

5.3 用 Playwright 技能排查前端 Bug

项目里有一个页面在移动端点击筛选按钮没反应。我把问题描述给 opencode，它的 Skills 机制自动匹配到了前端调试技能。接下来它自己做了几件事：

先启动开发服务器，再用 Playwright 打开页面，模拟移动端视口，点击按钮，查看控制台有没有报错。最后定位到是一个事件冒泡被父元素阻止了。整条排查路径非常像人：复现问题、看报错、缩小范围、找到根因。

整个过程我全程只负责看和确认，没有手动打开过浏览器。能做到这一点，核心就是 Skills 让 Agent 拥有了“使用工具”的能力，而不是干巴巴地生成建议。

5.4 把改动形成 Git 提交

任务完成后，opencode 会把改动的文件列出来，让我确认改动量。它会利用 Git 的 diff 能力来展示每个文件的变更差异，确认无误后我可以输入命令让它生成 commit message 并提交。这样一套流程下来，任务的“分析—编码—验证—提交”全部在终端里完成。

我也遇到过它一次性改动文件太多的情况，这时我会输入/undo撤销上一步操作，然后在需求描述里加上更严格的限定词，比如“只修改 src/services 目录下的文件”“不要动测试文件的结构”。

6. 常见报错与排查思路

结合我开头提到的那一堆热搜问题，这里把安装使用中最高频的报错整理成速查表，方便你遇到问题直接对号入座。

6.1 PowerShell 报错的变种问题

有些用户虽然把 PATH 加好了，但错误还是存在。这时可以在 PowerShell 里执行：

where.exe opencode

如果输出为空，说明 PATH 里确实没有；如果输出了一个路径，说明命令能定位到，问题可能出在 npm 包的安装损坏。可以执行：

npm uninstall -g opencode-ai npm install -g opencode-ai

卸载重装能够解决大部分半损坏状态的安装。

6.2 unexpected server error 的处理思路

这个报错出现的位置通常在启动或者某个功能调用时。它属于 opencode 自己的后端服务抛出的异常。常见场景有三个：

第一个是 opencode 版本太旧，缓存的数据结构和最新版不兼容。处理方式是更新到最新版，然后删除缓存目录。Linux/macOS 下缓存一般在~/.local/share/opencode/，Windows 下在%HOMEDRIVE%%HOMEPATH%\.local\share\opencode\或%APPDATA%\opencode下面。删缓存不影响你的配置和项目文件，但会丢失登录会话。

第二个是端口被占用。opencode 内部会起一个本地服务用于插件和 IDE 通信，如果端口被其他程序占用，也可能导致 unexpected server error。解决方案是找到并退出占用程序，或者重启电脑让服务端口释放。

第三个是配置文件写错。如果 opencode.json 引入了不存在的 provider 或 model，服务在启动时可能直接抛异常。建议把配置文件先用 JSON 格式化工具校验一遍，避免多逗号、少引号这类低级错误。

6.3 模型配置不生效的排查方法

配置了环境变量，但 TUI 里始终只看到默认模型，或者模型调用时提示认证失败，这种问题通常出在配置优先级上。opencode 读取的优先级是项目配置高于全局配置。如果你在两个地方都配置了 provider，且项目配置把 API key 写成了空字符串，那环境变量就会被“覆盖”成空。

排查方法很简单：在 TUI 里输入/status查看当前生效的配置，看看 provider 和 model 的实际值。如果你发现 key 没有正确从环境变量读取，重点检查 opencode.json 里的写法。推荐统一使用{env:变量名}这种引用格式，不要直接把 key 明文写进 JSON。

7. 和 Codex CLI / Claude Code 怎么取舍

7.1 我实际选择 opencode 的理由

使用了一段时间后，我个人的判断是：它和 Claude Code、Codex CLI 不是替代关系，而是同一类工具里不同取向的实现。

如果你用的是 Anthropic 全家桶，Claude Code 体验确实丝滑，上下文处理和对代码仓的理解都非常强。如果你重度依赖 OpenAI 生态，Codex CLI 自然很顺手。而 opencode 的价值在于它不做模型绑定，配置自由度更高，还能通过 Skills 扩展能力边界。

我最终把 opencode 作为主力终端 Agent，主要原因是“切换成本低”。今天想用 Claude 做代码设计，明天想用 GPT 查问题，后天想用本地模型处理敏感代码，不需要切换工具，只需要在/models里换个模型。

7.2 什么时候别用 opencode

反过来也有不适合用 opencode 的场景。首先，如果你完全不想看配置文件，也不想理解 Agent、Skills、Memory 这些概念，那直接用 IDE 插件会更容易上手。其次，如果你的团队已经统一用某一家模型的服务，并且深度依赖那家专属的上下文功能，那绑定厂商的工具体验可能更完整。

最后，如果项目的代码量非常庞大，比如一个巨型的 monorepo，那所有终端 AI Agent 都会面临上下文窗口的限制。这类工具的通用处理方案是先让 Agent 建立项目索引文件，再针对特定目录逐步深入，而不是让它一次性加载全部代码。这个使用习惯在 opencode 里同样成立。

7.3 接手线上项目时的个人体会

我在实际接手一个线上项目时，最深的一个体会是：这类工具能不能真正发挥作用，很大程度取决于你喂给它的“项目背景”。同样是“这个接口有问题”，如果你只扔给 opencode 一句话，它只能从代码层面试探性排查；如果你在 AGENTS.md 里写清楚了项目的模块划分、技术栈约定、常见坑，它就能直接命中要害。

所以我现在接手新项目的第一件事，就是花半小时让 opencode 读代码、写 AGENTS.md。项目背景越详细，后面每一次对话的效率提升越明显。这个投入非常值得。

8. 使用 opencode 过程中的几条避坑心得

最后分享几个实际操作中总结出来的经验，可能不算是官方文档里会写的内容，但确实能帮你少走弯路。

第一，非交互模式opencode run命令最好先加--model参数显式指定模型。因为全局默认模型可能不是你这次想用的那个，一旦跑起来才发现模型不对，既浪费 token 又浪费时间。

第二，让 opencode 做破坏性操作要谨慎。比如“删除无用的文件”这类任务，别看它自动列出了文件名，最好还是自己扫一眼。我在一次重构中就遇到过它把看起来没用但实际被动态引用的工具函数删掉的情况。所以涉及删除类的操作，建议在需求描述里明确写“只标记出来，不要直接删除”。

第三，把 opencode 和版本管理结合好。每次任务执行前，确保当前 Git 工作区是干净的，或者至少已经提交了一个可回滚的版本。这样即使 Agent 改了不该改的东西，也能靠git checkout快速恢复。

第四，如果发现 opencode 反应变慢或者行为变怪，优先检查版本更新。这个项目迭代速度非常快，一天一个小版本是常事。旧版本可能在某些模型接口或者 TUI 交互上存在已知问题，升级到最新版本往往就修好了。

第五，学会善用/undo。opencode 会记录最近的操作历史，如果某一步改错了，不要慌，直接撤销重来。对于复杂任务，我习惯让它一步一步来，每完成一步确认一次，而不是一次性把所有改动全部交出去，这样即使出错，回滚面也很小。

我第一次配置 opencode 的时候，其实也被 PowerShell 的报错卡了好一会儿，后来又因为不了解配置优先级走了弯路。但把它调顺之后，整个开发节奏确实快了很多。如果你也准备开始用这类终端 AI Agent，建议从一个小项目、一个明确的小任务开始，跑通之后再慢慢加 Skills、Memory、自定义 Agent。工具永远只是手段，最终还是要看它能不能真的帮你把活干完。