企业官网建设流程全解析

1. opencode 是什么：终端里的开源 AI 编程代理

如果你最近关注过 AI 编程工具，大概率绕不开 opencode 这个名字。我第一次认真用它，是因为当时项目里同时在测 Claude 和 OpenAI 的模型，而 Claude Code 对模型锁得比较死，Codex CLI 在复杂仓库里的上下文又不够顺手。opencode 是 SST 团队开源的一个本地优先、终端优先的 AI 编程 agent，支持 Claude、OpenAI、Gemini，也能接 Ollama 这类本地模型，以及各种 OpenAI 兼容网关。2.x 版本之后，它的会话管理、子代理、技能系统已经能覆盖我绝大多数日常工作。

它不是又一个聊天机器人。你在终端里启动 opencode，它会先读完你的项目结构，再根据你的需求做计划、改文件、跑命令、看测试结果，整个过程保留明确的审批节点。换句话说，它更像一个坐在你旁边、能自己动手的实习生，而不是一个只会在对话框里给你贴代码片段的助手。对于已经用过 Claude Code 或 Codex CLI 的人来说，上手成本非常低；对于想从 IDE 插件迁移到更自动化工作流的人，opencode 也是一个很合适的落脚点。

1.1 不是又一个对话机器人，而是能自己动手的 agent

核心区别在于“行动力”。你在 opencode 里说“把 issue 42 修复掉”，它会自己去翻 issue、定位相关代码、改文件、跑测试，然后把 diff 摆在你面前。遇到不确定的地方，它会停下来问你。这背后是一套基于终端的能力边界：读写文件、执行 bash 命令、启动开发服务器、调用 MCP 工具，全部通过权限模型控制。

我把这种模式理解成“放权但不放养”。一开始我习惯把它的权限设成每步都问，后来发现太啰嗦；改成默认允许读文件、跑测试，但写文件和执行破坏性命令必须确认之后，效率才真正上来。opencode 的好处是配置文件就在项目里，团队可以约定同一套权限规则，而不是靠每个人自己嘴上约束。

另外，opencode 是开源项目，数据默认留在本地。它的会话、配置、技能目录都以普通文件形式存在，不依赖某个云账号。这点和很多商业工具完全不同，也是它在我这里能长期占一个终端窗口的原因。

1.2 它和 Claude Code、Codex CLI、Cursor 的定位差异

很多人纠结选哪个。我自己的判断标准很简单：看你是不是在意“模型自由”和“工具开放性”。官方工具通常和自家模型配合最顺，但如果你想在一套工作流里切换多个模型，或者希望记住的 prompt、技能、配置可以被版本管理，开源方案会更省心。

还有个容易忽略的点：社区里新出现的终端 agent 越来越多，比如有人会拿 opencode 和pi之类的新工具对比。我的建议是别看宣传，直接拿真实仓库试半小时，重点看三件事：粘贴长上下文后会不会乱、改错文件后能不能救回来、以及技能/MCP 生态是否活跃。工具迭代太快，一个项目只要不更新，半年后体验就是两个时代。

2. 安装、登录与第一次对话

opencode 安装本身不复杂，但它是一个终端优先工具，很多新人的第一道坎反而是“装完打不开”。我在这部分把不同平台的安装方式和第一次配置讲清楚，顺便把常见的 PATH 问题一次性说透。

2.1 macOS / Linux / Windows 安装

官方推荐安装方式是一键脚本。macOS 和 Linux 上，我一般用这条命令：

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

如果你和我一样用 Homebrew，也可以走 brew 安装，升级会比较方便：

brew install sst/tap/opencode

Windows 上官方提供了 PowerShell 安装脚本，我在自己电脑上实测过，新版 Windows Terminal 直接执行就行：

irm https://opencode.ai/install.ps1 | iex

有一点值得单独说：opencode 是 Go 写的，发布物是单文件二进制，没有 Node 运行时依赖，所以启动极快。正因为它是个独立二进制，升级和卸载都很干净，但也正因如此，安装脚本默认把二进制放到~/.opencode/bin这种目录，能不能直接识别成命令，完全取决于 PATH 里有没有这个路径。如果你有 Go 环境，也可以go install github.com/sst/opencode@latest，我偶尔在容器里用这种方式，好处是版本跟得很紧，坏处是遇到跨平台编译问题要自己处理。

2.2 第一次运行：API Key 与模型选择

装完之后不要急着对话，先把模型供应商配置好。opencode 本身不生产模型，它只是一个代理，最终调用哪个模型，需要你提供 API Key 或本地模型服务。最常见的做法是设置环境变量，比如用 Anthropic 的模型：

export ANTHROPIC_API_KEY=sk-ant-...

如果你用 OpenAI 兼容的近几十种网关，思路一样，改成对应的 API Key 环境变量就行。配置好后，在项目目录里直接运行：

opencode

它会启动一个全屏 TUI。第一次进来，你可以直接输入自然语言任务，比如“给我讲讲这个项目怎么跑起来”，它会读代码、看文档、列依赖，最后给你一份说明。如果你当前的版本支持opencode auth login，也可以走账号登录流程，但我在团队项目里更推荐环境变量方式，因为 CI 和本地可以共用同一套配置，换人不换 key。

还有个容易被忽略的点：opencode 的模型切换非常灵活。你可以在运行时切换，也可以在配置文件里指定默认模型。我通常把“快而便宜”的模型作为默认，比如处理日志、重构小函数这类任务，只有遇到架构级问题时才切到更强的模型。这个习惯帮我省了不少 token，也让日常会话速度更快。

2.3 安装后立刻遇到的 PATH 问题

在 Windows 上，最常见的报错是：

opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名

这句话的意思是系统在 PATH 里找不到 opencode 这个可执行文件。解决方法分成三步。第一步，先确认文件到底装到了哪里：

where.exe opencode

如果提示找不到，就去用户目录的.opencode\bin看一下。第二步，把这个目录加到用户级 PATH 环境变量。第三步，关掉当前终端再重新打开，让环境变量刷新。macOS 上如果遇到command not found，多半也是同样问题，手动把~/.opencode/bin加进 shell 配置文件即可。

安装后如果 IDE 插件也提示找不到 opencode，不要只重启终端，还要重启 IDE。插件启动时读取的环境变量来自父进程，终端里的 PATH 不会自动同步到 IDE 里，这一点我在 VS Code 和 JetBrains 系里都踩过。

3. 配置才是关键：模型、套餐、项目级上下文

很多人用这类工具只停留在“对话里加 prompt”，但真正拉开体验差距的是配置文件。opencode 的项目级配置、全局上下文和记忆机制，决定了一个 agent 是像“第一次进仓库的实习生”，还是像“跟你合作半年的老同事”。

3.1 opencode.json 里该配什么

进入项目后，我一般先执行opencode init，它会生成一个基础配置文件。不同版本字段名略有差异，但核心模块是稳定的：provider 负责模型供应商，permission 负责权限边界，mcp 负责外部工具，skills 负责技能包。我常用的一个最小配置长这样：

{ "$schema": "https://opencode.ai/config.json", "provider": { "default": "anthropic", "anthropic": { "api_key": "env:ANTHROPIC_API_KEY", "model": "claude-sonnet-4-5" } }, "permission": { "default": "ask", "deny": [ "bash:git push" ] } }

这里最关键的是权限配置。我建议新人在头一周把permission.default设成ask，让每个重要操作都过一遍你的眼睛。等熟悉了它的行为模式，再逐步放开。我在配置里长期保留deny: git push，因为 agent 代写提交信息没问题，但推送远端这个动作，我想保留在可控的流程里。

配置文件还有一个大用处：可以提交到 Git 仓库。这样团队成员 clone 下来之后，不需要各自凑 prompt，就能共享同一套模型选择、权限边界和 MCP 工具。团队落地 AI agent，配置文件的统一程度直接决定了工具使用规范程度。

3.2 AGENTS.md 与 Memory：让 agent 记住项目约定

opencode 的 Memory 功能，我理解成给 agent 开了一个不会忘事的笔记本。但比记忆更稳定的做法，是把团队约定写进项目根目录的AGENTS.md。这个文件会被 agent 在启动时读取，相当于你每次开会前先给它一份“项目手册”。

我通常会在AGENTS.md里写这几类内容：

# 项目约定 - 测试命令：npm test - 禁止直接改动 package-lock.json - 新功能必须补测试 - git 提交信息使用 conventional commit - 修改 API 前先查看 docs/api.md

写完之后，你会发现 agent 的行为立刻变得“懂规矩”了。它不会再一上来就乱装依赖，也不会随便改锁文件。全局性的个人习惯可以放在用户主目录下的全局配置里，仓库级的规范放在AGENTS.md，一次性任务上下文放在 prompt 里，这个三层结构是我用下来最稳的信息组织方式。

很多人以为是“模型聪明就够了”，其实不是。模型再聪明，也不知道你们项目里谁负责哪个目录、测试要用什么命令、历史上有哪些坑。这些信息只有靠AGENTS.md和 Memory 机制持续喂给它，模型才能真正从“会写代码”变成“会写你们项目的代码”。

3.3 免费模型、本地模型和套餐怎么选

先说清楚一件事：opencode 工具本身免费，但这不意味着调用模型不要钱。官方也提供统一 API 套餐，本质是先充值再按 token 结算，好处是不用分别管多个厂商的账户，一个 key 就能用不同模型。套餐档位和计费倍率会随上游变动，我个人的建议是别急着买大额套餐，先用消耗低的模型跑两天，看你的实际使用量再决定。

社区里经常有人分享“免费模型通道”，比如之前传过一阵的 hy3-free 之类的名字。我的态度比较保守：免费通道适合拿来玩、做 demo、验证流程，不适合放生产环境。因为这类通道上下线频繁，经常排队，稳定性完全取决于维护者的心情。你正在改一个紧急 bug，结果模型 provider 挂了，这种体验一次就够受的。

本地模型是另一个方向。如果你有 Ollama，只需要在 opencode 里配一个 OpenAI 兼容的本地服务地址：

{ "provider": { "ollama": { "url": "http://localhost:11434/v1", "model": "qwen3-coder" } } }

本地模型的好处是隐私和数据安全，成本也低，但代码生成质量和中大规模仓库的理解能力，跟顶级商用模型比还有差距。我现在的分工是：本地模型处理日志分析、批量文本改写、简单脚本；商用模型处理架构设计、复杂测试、跨模块重构。这种组合既省钱，又不牺牲质量。

3.4 用 cc-switch 这类工具管理多套配置

用 opencode 越久，你会发现自己手上的配置越多：家用电脑一套、公司项目一套、客户环境一套，每套可能要配不同的 API Key、模型和权限策略。手动去改 JSON 文件很容易出错，尤其是多台设备之间同步时，漏改一个字段就会导致 agent 行为偏离预期。

cc-switch 这类工具解决的就是这个问题。它提供了一个图形化或命令行的配置切换界面，把 opencode、Claude Code、Codex 等工具的配置集中管理起来。你可以在里面保存多份 profile，按项目一键切换。尤其是命令行版或者说“opencode go”这种偏 nerd 的用法，没有图形面板辅助时，配合 cc-switch 这类工具能省下大量改配置的体力活。

我的习惯是：项目级配置入库，全局密钥不入库。目录里放一个opencode.json，里面的 key 用env:方式引用环境变量；cc-switch 负责管理不同场景的全局 profile，把对应的环境变量或配置片段切到当前 shell。这样即使配置切换出错，也不会把密钥真正泄露到 Git 里。

4. 进阶玩法：Skills、MCP 与前端 bug 排查

配置文件打好底子之后，接下来就是 opencode 真正值钱的地方：技能系统和外部工具接入。这两样东西让 agent 从“通用程序员”变成“懂你项目流程的专用助手”。

4.1 Skills 和 superpowers 插件包

Skills 可以理解成给 agent 预装的“工作模板”。比如你经常做 UI 走查，就写一个ui-review技能，里面规定好要看哪些页面、检查哪些指标、用什么输出格式。以后每次只要说“用 ui-review 看一眼登录页”，它就会自动按流程走，不用你每次重复描述需求。

技能包本质上是一组目录和 markdown 文件。常见的结构大致是：

~/.config/opencode/skills/ui-review/ ├── SKILL.md ├── system.md └── prompt.md

SKILL.md是入口说明，system.md是给模型的系统指令，prompt.md是用户侧会看到的提示词模板。我一开始觉得写技能很麻烦，后来发现这跟写测试用例一样，投入一次，长期受益。

社区里很多人提到的 superpowers，就是一套成熟的 skills 合集，覆盖代码审查、重构、前端调试等场景。如果你以前用过 oh-my-claudecode 这类配置包，会发现很多 prompt 思路可以平移到 opencode。安装时留意一件事：技能目录的扫描路径在不同版本里可能不一样，clone 完先看一下当前版本实际读取哪个目录，别装完发现没生效。

4.2 接 Playwright 测前端 bug

用 opencode 做前端开发时，最大的痛点是它看不到界面。解决思路有两种，一种是让它直接跑 Playwright 脚本，另一种是接 MCP 浏览器工具。我更推荐后者，因为交互更自然，你可以直接说“打开页面，点那个按钮，看 console 报错”。

在opencode.json里加一个 Playwright MCP 服务：

{ "mcp": { "playwright": { "command": "npx", "args": ["@playwright/mcp@latest"] } } }

重启 opencode 之后，你就能在对话里让它用浏览器操作页面。我经常这样描述 bug：“用 Playwright 打开 localhost:5173，进入设置页，勾选两个选项，然后提交。复现一下这个场景里的报错，把 console 和 network 里的失败请求列出来。”它会自己启动浏览器、执行操作、收集信息，然后结合代码定位问题。

这里有个很实用的排查技巧：如果 Playwright 启动浏览器失败，先检查是不是没有安装 Chromium，直接让 agent 运行npx playwright install chromium。如果页面需要登录态，可以先把登录后的 cookie 文件路径告诉它，或者提前用playwright codegen录制一条稳定路径，避免每次都卡在登录上。

4.3 用 subagent 提效的思路

opencode 里可以开多个子 agent，我把它当成“分工”来用。一个 agent 专门看日志、整理报错，另一个 agent 同时去改代码。主 agent 负责调度，最后把两个结果合并。这个模式特别适合定位跨模块 bug，比如前端报错、后端异常、数据库数据不一致同时出现的情况。

但别一上来就开一堆 subagent。context 有限，信息窗口会被撑爆。我常用的做法是：先让一个 agent 把问题收敛到具体文件和函数，再针对这个范围派第二个 agent 去做修改。范围越小，子 agent 的效果越明显；一上来就给一个十万行仓库让它自由探索，反而容易跑偏。

5. 日常实操：从接手项目到提交代码

配置和技能都齐了之后，日常开发就变成一个“如何把需求清晰描述出来”的问题。这里分享一些我在真实项目里反复使用的流程和注意点。

5.1 一句话开始一个务实任务

我不会把 opencode 当成无所不能的架构师，而是把它当成一个“行动力很强的执行者”。所以我给它任务时，会刻意写清楚目标、边界和验证方式。比如：

opencode "修复登录页在移动端点击登录按钮无响应的问题。先看一下最近的 console 报错，定位到具体组件，修复后跑一遍现有的登录相关测试。"

这个 prompt 包含了目标、线索、动作范围和验证条件。对比一下“帮我修个 bug”这种模糊说法，效率差距非常大。更进阶的做法是让 agent 自己建分支、改代码、跑测试、生成提交说明，最后把分支 push 到远端。当然，push 这一步我通常手动执行，因为我要在 push 前看一遍 diff。

还有个小技巧：如果项目很大，先问它“这个项目的目录结构是怎么组织的”，等它读完再给任务。这样相当于先让 agent 建立心智地图，后续改代码会准确很多。直接甩一个任务进去，它往往会在无关目录里浪费时间。

5.2 Java / Maven 项目里的注意点

Java 项目里跑 opencode，最常遇到的问题不是模型，而是构建环境。假如你的项目用 Maven，但本机没配JAVA_HOME，agent 执行mvn test就会失败，它会带着一脸问号反复重试。所以我在项目根目录的AGENTS.md里会特别写清楚：

- Java 版本要求：17 - 构建命令：./mvnw clean test - JAVA_HOME 位置：/opt/jdk-17

用./mvnw而不是裸mvn是个好习惯。Maven Wrapper 会把构建环境固定下来，agent 执行的时候不会因为你本机装了不同版本的 Maven 而行为异常。如果你确实需要让 agent 直接用 mvn，那就确保mvn -v在任何一个新开的终端里都能正常运行，否则 IDE 插件里启动的 agent 可能继承不到环境变量。

Java 项目还有一个特点：编译慢。如果每次都让 agent 全量编译，成本很高。我一般让它用-pl指定模块，或者先mvn compile -DskipTests快速验证语法，再在关键节点跑完整测试。这个思路同样适用于大型前端 monorepo，先用tsc --noEmit做类型检查，再跑具体测试文件。

5.3 VS Code / JetBrains 插件怎么配合

opencode 的终端 TUI 体验已经很完整，但大部分人还是习惯在 IDE 里看 diff。VS Code 插件和 JetBrains 插件我都试过，工作方式其实很像：安装扩展后，选择本机的 opencode 二进制路径，然后在侧边栏或面板里打开项目，就能直接开始对话。

IDE 插件最大的优势是 diff 视图。agent 改完代码之后，你能像 review 同事代码一样逐行看变更，该撤回的撤回，该保留的保留。相比之下，终端里看 diff 虽然也支持，但遇到跨多文件的改动，体验还是不如 IDE 直观。

关于“桌面版”，我看到过一些社区封装，也有官方方向的尝试。我的看法是：桌面版和 IDE 插件本质都是给同一个 opencode 核心套了一层壳，最终读的还是同一份配置和会话目录。所以不用纠结用哪个入口，核心能力都在底层。我现在的主力组合是：终端里跑 TUI 处理复杂任务，IDE 插件负责 diff review 和小范围修改。

6. 高频问题与避坑实录

最后这部分是我实际使用中踩过的坑，以及经常在社区里看到的问题。整理成一张速查表，再分享几个长期省心的习惯。

6.1 常见报错速查表

这里想单独说一句unexpected server error。我见过不少人在群里焦虑，以为是 opencode 坏了，其实绝大多数时候是上游 API 服务抖动，或者某个免费通道下线了。排错顺序应该是：先换一个模型测试，如果其他模型正常，说明是原模型供应商的问题；如果所有模型都报错，再检查本地配置和网络连接。别一上来就重装工具，浪费时间。

6.2 我用 opencode 半年后想告诉你的几件事

第一，权限配置一定要先收紧再放开。新手最容易犯的错误是图省事，把权限设成“全自动”，结果 agent 在你没注意的时候跑了一堆破坏性命令。我见过最夸张的一次是它把整个node_modules删掉重装，虽然理论上没错，但那个等待时间真的很疼。正确做法是先全 ask，跑一周，再根据实际需要逐步放权。

第二，AGENTS.md值得花时间认真写。很多人觉得这是额外负担，但你写一次，后面所有会话都在复用。尤其是团队协作时，一个结构良好的项目说明文件，能让每个成员用 agent 的体验都稳定在同一水平线上。反过来，如果每个人各写各的 prompt，结果就是十个 agent 有十种开发风格，团队 review 成本直接上升。

第三，不要让免费模型承担核心生产任务。免费通道适合测试和体验，一旦项目进入交付阶段，稳定的付费模型是值得投入的成本。我之前接过一个需求，用一个免费通道跑了三天，每天掉线两次，后来算下来浪费的时间早就超过了那点 token 费用。

第四，每次让 agent 做完修改，至少自己读一遍 diff。这不是不信任，而是在建立对工具行为的直觉。读 diff 时你会慢慢发现它擅长什么、容易在哪类问题上犯错，后面给 prompt 时就知道该重点强调什么。工具用得好的团队，都是先对人负责，再对工具放权。