企业官网建设流程全解析

要说最近一年开发者工具里最热闹的方向，AI 编程 Agent 肯定排第一。各种号称“能替你写代码”的产品轮番上场，有的重在 IDE 里补全，有的主打聊天框生成，真正愿意做成纯命令行、还强调 100% 开源的，OpenCode 算是特别的一个。我第一次在终端里完整跑通它的 Agent 流程之后，第一反应是：原来不依赖任何闭源的商业客户端，也能把“拆需求、读代码、改文件、跑命令、看报错”这套活儿在本地闭环做完。

它不是一个网页插件，也不是 IDE 里的侧边栏，而是一个跑在终端里的编程代理。你给它一个任务描述，它会自己读项目结构、打开相关文件、修改代码、执行命令，然后根据报错继续调整，直到任务完成。全程你能看到每一步它做了什么，也可以随时喊停。适合谁呢？我觉得最适合三类人：一是重度依赖命令行的老手，二是想尝试 Agent 但不想被某个商业客户端绑住的人，三是希望在团队里沉淀一套可配置、可审计的 AI 工作流的负责人。

1. 先搞清楚一件事：OpenCode 到底解决了什么问题

1.1 AI 编程 Agent 和普通代码补全工具的差别

要理解 OpenCode 的价值，得先分清“代码补全”和“编程 Agent”这两个东西。代码补全工具像是输入法，它根据你当前光标位置和最近的代码，预测你接下来可能要写的几个字符或几行代码。它本身不“理解”整个项目，也不会主动去运行测试、查看报错、修改多个文件。本质上是给你的打字速度做一个加速，而不是帮你做决策。

编程 Agent 则完全是另一套逻辑。它更像一个坐在你旁边的实习生：你给它一个目标，它会自己翻项目目录、打开相关文件、理解现有代码结构、设计修改方案，甚至直接执行命令来看结果。关键区别在于“行动能力”——Agent 不是生成一段文本让你复制粘贴，而是会真的去读写文件、运行命令、根据输出调整下一步动作。

我常用的类比是：补全工具好比菜谱 APP 告诉你“下一步该放盐”，而 Agent 是一个能帮你买菜、洗菜、开火、试味道的全流程帮厨。OpenCode 属于后者，而且它把这个“帮厨”的所有动作都摆在桌面上，每一步做了什么、动了哪个文件、执行了什么命令，全部可见、可控、可审计。

这种“可见性”非常重要。编程 Agent 的能力边界来自模型，但行为边界来自工具和权限。一个不可见的 Agent 改坏了代码你都不知道它从哪里动的手，而 OpenCode 这类终端原生工具天然适合做细粒度控制——每个文件写入、每条命令执行，都可以在终端里被拦截、询问、允许或拒绝。

1.2 为什么终端形态加上 100% 开源这么重要

市面上不少 AI 编程助手选择做成 IDE 插件或独立桌面应用，这没问题，但会带来两个隐形成本：一是你的工作流被绑定在特定编辑器生态里，二是你很难看清楚这个工具到底把你项目里的哪些文件发给了哪个模型服务。终端形态的 OpenCode 绕开了这两点。

终端的好处非常实在。第一，它不挑环境，本机、远程开发机、容器里都能跑，只要是能开 shell 的地方就能用；第二，它方便和现有工具链串起来，写完代码自动触发 Agent 做审查、跑测试、提交信息生成，这些在终端里可以轻松嵌入脚本和钩子；第三，资源占用低，不需要多一个常驻 GUI 进程吃内存。

再来说“100% 开源”这个承诺。开源在这里不是情怀，而是几个实打实的能力保障：模型供应商可以自由切换，不用被特定厂商锁定；所有配置都在本地文件里，团队可以统一管理；最关键的是，你可以直接看源码确认它到底什么时候读了文件、什么时候发了网络请求、发了哪些内容。对于代码保密要求比较高的团队来说，这是商业闭源工具给不了的确定性。

顺便说一下，很多人对开源工具的印象是“难用、文档差、要自己折腾”。OpenCode 在这点上做得还不错，安装路径短、配置文件直白、上手成本不算高，后面我会把从安装到配置的完整流程拆开讲。

2. 安装与初始化：从零到能用只要一条命令

2.1 安装方式与版本选择

OpenCode 的安装方式有好几种，我按推荐程度排一下。最省事的是用官方提供的一键安装脚本，官方文档里的 curl 安装命令，拉下来直接执行，会自动装到用户目录并把可执行文件放进 PATH，不需要 root 权限。第二种方式是通过 Node 生态的全局包管理器安装，适合本来就装了 Node 环境的开发者，装完就有了opencode命令。第三种是直接下载编译好的二进制包，放到你自己的工具目录里，适合对安装过程完全有洁癖的人。

装完之后在终端输入opencode，能进入交互界面就说明基础环境没问题。如果你打算在脚本和非交互场景里调用，可以留意下官方有没有提供独立的单次执行子命令，比如opencode run "你的任务"这种形式，用起来会顺手很多。

版本选择这块要专门提个醒。这类工具迭代速度非常快，新版本可能每天都有功能变化，配置字段、命令名都有可能调整。我的建议是：个人尝鲜用最新版没问题，但如果是团队统一使用，尽量锁死在同一个版本，别让大家“各用各的版本”，否则配置文件很容易在有些人那里报错。还要注意更新前看一眼更新日志，确认权限策略、配置结构这类破坏性变更，别盲目升级。

安装过程中比较容易踩的坑是网络下载慢。官方安装脚本会从发布渠道拉包，有些网络环境下会很慢甚至失败。碰到这种情况，换个镜像源或者手动下载二进制包基本能解决。另外一个坑是 PATH 没写入，装完提示成功，但opencode命令找不到，检查一下家里目录下的环境变量配置就行。

2.2 模型接入配置：第一次启动前要做的事

OpenCode 本身不内置任何模型，它更像一个“模型兼容外壳”，负责把你的任务、项目上下文、工具调用结果组织成模型能理解的消息，再调用各家模型服务的接口。所以第一次使用前，必须先把模型接入配置好。

配置模型有两种常用方式。一种是通过交互式登录命令，比如opencode auth login，按提示选择你要用的服务商并完成认证，工具会帮你把凭据安全地存好。另一种是直接编辑配置文件，手动指定模型供应商和模型名，这种方式更透明，也更容易在团队里复制。

我习惯用配置文件的方式，格式大概是这样的：

{ "$schema": "https://opencode.ai/config.json", "model": "my-provider/my-code-model", "provider": { "my-provider": { "options": { "apiKey": "你的 API Key" } } } }

注意model字段的格式是“供应商名/模型名”这样一段拼接的字符串，写成my-provider/my-code-model就表示“用 my-provider 这个供应商提供的 my-code-model 这个模型”。API Key 可以直接写在配置文件里，但更安全的做法是通过环境变量注入，后面我会专门讲这个。

如果你不想依赖云端的模型服务，OpenCode 也支持接入本地模型。做法是在某个供应商配置里指定一个本地模型服务的地址，把它当成协议兼容的供应商来用。这样所有请求都在本机走一圈，数据完全不出内网，对保密要求高的项目很关键。当然代价是本地模型在复杂代码理解上的能力可能弱一些，建议简单任务用本地模型，重活再切到云端大模型。

2.3 配置文件结构与项目级规范

OpenCode 的配置体系分为用户级和项目级两层。用户级配置放在你用户目录下的配置目录里，负责全局默认的模型、权限策略、全局自定义 Agent。项目级配置放在项目根目录里，可以覆盖某些全局设置，也可以给当前项目单独定义 Agent 和工具。这种分层方式非常实用，因为你可以在全局设置一个通用模型，然后在某个特定项目里指定另一个更适合该技术栈的模型。

除了 JSON 配置文件，还有一个东西强烈建议用起来：项目说明文件，也就是在项目根目录放一个 AGENTS.md。这玩意儿是给 AI 看的“团队新成员入职手册”。你可以在里面写清楚项目用的语言和框架、目录结构约定、代码风格、测试怎么跑、哪些目录不能动、提交信息规范等等。每次 Agent 在这个项目里执行任务时，会自动读取这份文件作为背景知识。

我给你看一个最简单的 AGENTS.md 示例：

# 项目规范 - 语言：TypeScript，禁止使用 any - 测试：放在 src/test 目录，改完代码必须跑关联测试 - 目录：src/core 是核心逻辑，src/ui 是界面层，不要跨层调用 - 提交信息：使用 conventional commits 格式 - 禁止：修改 public 目录下的产物文件，不要执行清理脚本

把这类约定写清楚后，Agent 的行为质量会明显上升。它不再是“猜一个开发者的习惯”，而是照着项目既有的规则去干活。我见过很多人抱怨 AI 编程助手“改出来的代码风格不对”，其实一半的问题出在根本没给 Agent 提供项目规范。AGENTS.md 就是解决这个问题的标准做法。

配置好模型和项目规范之后，这个基础就算打牢了。接下来才进入真正好玩的部分：看 OpenCode 是怎么把“一个任务描述”变成“一系列具体操作”的。

3. 核心功能拆解：终端里的 Agent 是怎么工作的

3.1 全屏交互与单次执行：两种运行模式怎么选

OpenCode 提供的交互入口可以分成两种形态。第一种是全屏交互模式，直接运行opencode进入一个终端图形界面，里面有会话历史、可以多轮对话、能看到工具调用过程和文件差异。这种模式适合你坐在电脑前和 Agent 一起干活，边看边改，随时插话纠正。

第二种是单次执行模式，用类似opencode run "任务描述"的方式，把任务作为参数传进去，它在后台跑完整个流程后把结果输出出来。这种模式的价值在于“可以被脚本调用”，可以在提交代码前自动跑一遍代码审查，可以在 CI 流程里让 Agent 根据报错信息给出修复建议，也可以做一个定时任务自动整理某个目录的代码。对我来说，单次执行模式把 Agent 从一个“聊天对象”变成了“可编程的工具”，这是它最大的想象力所在。

进入全屏交互模式之后，界面里通常会有几个高频命令值得先记住。输入/help可以看当前版本支持的所有命令；/init可以让 Agent 根据当前项目自动生成一份 AGENTS.md 初稿；/compact可以把冗长的历史对话压缩成摘要，节省后续请求的消耗；/agents用来切换不同的自定义 Agent；/models可以快速切换模型。不同版本的命令名可能略有差异，自己进去先敲一遍/help就行。

这里有一个实际体会：不要在一个会话里堆太多无关任务。Agent 的上下文窗口是有限的，历史聊得越长，它真正用来“思考当前任务”的空间就越小，而且费用也会涨。一个任务开一个会话，做完就开新的，效率和成本都更划算。

3.2 工具调用与权限控制：给 Agent 装一个“刹车”

Agent 和普通聊天机器人最大的不同就是它能调用工具，而工具意味着“能真正改变东西的能力”。OpenCode 内置了读文件、写文件、执行命令等常见工具，这些工具如果完全不受控，Agent 可能在你仓库里跑出各种意想不到的操作。所以权限控制是使用这类工具时最先要建立的安全意识。

OpenCode 的权限机制思路很清晰：对不同类型的操作设置不同的放行策略。常见的策略模式可以分为几档。最保守的一档是“先规划再执行”，Agent 只允许做读操作，所有写文件和执行命令的动作都先展示出来等你确认；中间档是“关键操作逐个询问”，读文件直接放行，写文件、跑命令时提示你允许本次还是拒绝；最激进的一档是“信任直通”，所有操作直接放行，适合你自己完全清楚风险的一次性环境。

给我的建议是：日常开发用中间档，让 Agent 有足够的自主性做读操作和分析，但写文件和执行命令这类“会产生副作用”的动作卡一道关。等到你完全信任这个 Agent 在某个项目里的表现，再考虑放宽。不要一上来就开信任直通，尤其是公司共享的开发机上。

权限配置在 JSON 里只需要一个字段，比如：

{ "permission": "normal" }

具体枚举名以你本地版本的/help输出为准，不同版本命名可能有差异，但思路都是“从只读、到询问、到放行”的阶梯。

3.3 自定义 Agent：把助手调教成团队里的不同角色

默认情况下，OpenCode 里的 Agent 是一个什么都会一点的通用编程助手。但实际开发中，我们需要的往往不是“万能的人”，而是“不同角色”。比如代码审查是一个角色、重构是一个角色、写文档是另一个角色。把任务和角色匹配好，产出质量会高非常多。

OpenCode 支持在配置里定义多个自定义 Agent，每个 Agent 可以设置自己的名称、系统提示词、使用的模型，甚至限定它能调的工具有限。比如你可以定义一个“严格的代码审查者”，提示词里写清楚“你只做审查不做修改，发现逻辑问题、性能隐患、风格问题时要给出具体的修改建议，并指出对应代码位置”。这样一个 Agent 就能一件事做到底，不会一边说问题一边手贱改了代码。

配置自定义 Agent 的结构大致是这样：

{ "agents": { "code-reviewer": { "prompt": "你是一个严格的代码审查者。只审查，不修改代码。发现问题时指出文件路径和行号，并给出修改建议。", "model": "my-provider/my-review-model" }, "refactor-agent": { "prompt": "你是重构专家。需要先分析现状，再给出重构方案，确认后才动手。", "model": "my-provider/my-code-model" } } }

定义好之后，在全屏交互界面里用/agents就可以在角色之间切换。团队使用时，这套自定义 Agent 配置可以统一放在团队共享的配置文件里，让所有人用同一套“标准角色”，这对团队协作的体验提升非常明显。

实践经验告诉我，自定义 Agent 的提示词不要写得太抽象。与其写“你要注意代码质量”，不如写“确保新代码与现有风格一致、不允许引入新的全局状态、必须有对应测试”。给 Agent 清晰的约束和输出格式，它交给你的东西基本能一次成型。

3.4 MCP 扩展：让 Agent 长出“手”来

内置工具解决了“读写文件、执行命令”这些基础需求，但真实世界的开发场景远不止这些。你可能希望 Agent 能查数据库表结构、能调用浏览器看看页面效果、能读取外部服务返回的数据。这时候就要用到 MCP（模型上下文协议）了。

MCP 本质上是一个标准化的“外设接口”协议，它让 Agent 能够连接外部工具服务器，并通过统一的格式调用这些服务器提供的能力。你不用关心每个工具内部怎么实现，只需要在配置里声明“我要连接哪些 MCP 服务器”，Agent 就能在需要时调用对方暴露的工具。

配置 MCP 服务器的示例大概是：

{ "mcp": { "web-fetch": { "type": "stdio", "command": "npx", "args": ["-y", "某个抓取网页的 MCP 工具包"], "env": {} } } }

配置好之后，你可以在一个会话里让 Agent 自己打开一个本地页面的地址、检查渲染结果、对比样式差异，然后根据结果改代码。这个能力其实非常颠覆，相当于 Agent 从“只在代码层面工作”升级到了“能在真实运行环境里验证自己的产出”。

不过 MCP 也要注意边界。每接入一个 MCP 服务器，Agent 的可用工具列表就多一截，你的上下文被工具描述占用的空间也就更多。不是工具越多越好，而是够用就好。另外，MCP 服务器本质上是本地子进程，来源不明的工具包要谨慎加载，别把第三方 MCP 当玩具乱接一通。

4. 架构原理与请求链路：Agent 背后是怎么转起来的

4.1 整体架构分层

用起来顺手是一回事，能把它用出深度是另一回事。想真正驾驭 OpenCode，还是得理解它的三层架构。

最上层是终端交互层，负责你看到的界面、输入输出、流式渲染。这一层的作用是把 Agent 的内部运作“可视化”出来——哪些工具被调用了、输出什么内容、文件差异长什么样。它不参与任何智能决策，纯粹是人和 Agent 之间的桥梁。

中间是 Agent 运行时，这是最核心的编排器。它负责维护当前会话的目标、记忆、上下文窗口，决定下一步调用模型还是调用工具，处理多轮对话的逻辑流转。你可以把它理解成一场演出的导演：模型是演员，工具是道具，导演决定什么时候让演员上场、什么时候换道具。

最下层是执行与适配层，包括各家模型服务提供商的适配器、内置文件与命令工具、MCP 客户端和权限守卫。适配器的存在让 OpenCode 可以对接不同供应商的模型，而权限守卫则在每一个工具调用发生之前做检查，决定这个动作允不允许执行。

这三层结构几乎是同类工具的通用形态。搞清楚之后，你就知道某些问题该去哪个层面排查：界面卡了查交互层，任务逻辑不对查运行时，模型报错或者工具不能用，大概率是适配层和配置的问题。

4.2 一次任务请求的完整执行链路

把一个普通任务拆开看，Agent 的一次完整执行链路其实是一个循环迭代的过程。

第一步是你输入任务描述，比如“帮我给登录接口加上防重放校验”。第二步，Agent 运行时开始组装上下文：当前系统提示词、项目根目录的 AGENTS.md、最近的会话历史、以及它认为相关的文件内容，全部打包成发给模型的请求。第三步，模型接收到这些信息后，返回一个响应。这个响应可能是文本，也可能是一个“工具调用请求”。

如果是工具调用，第四步就轮到权限守卫登场了。它会根据当前设置的权限策略判断：这个读文件操作能不能直接放行？这个写文件操作要不要弹窗询问？这个执行命令的权限够不够？通过之后，第五步真正执行工具，比如读取某个文件、运行某个测试。第六步，工具执行的结果——文件内容、终端输出、报错信息——被回填到会话上下文里。

然后整个循环再回到第三步，模型基于新的上下文继续推理。它会判断“问题解决了没有”，没解决就继续调用下一个工具，解决了就输出最终结果。这个“模型推理—调用工具—反馈结果—再推理”的循环，就是 Agent 的核心运转逻辑。

理解这个链路对排查问题特别有帮助。比如 Agent 一直改不对代码，可能是它根本没被喂到关键文件的内容；比如它反复跑同一个命令，可能是工具执行结果没有正确回填让它误判了状态。这些问题在理解了执行链路之后，都能快速定位到具体环节。

4.3 上下文管理与成本控制

Agent 每发一次模型请求，都要把当前会话的上下文全部打包发送。上下文越长，请求越慢、费用越高，而且模型的理解力还会被无关信息干扰。想让 OpenCode 跑得又快又省，上下文管理是必修课。

我最常用的两个手段，一个是/compact命令。当会话变得很长，Agent 开始“忘事”或迷失重点时，我会让它把现有对话压缩成一段简洁摘要，然后基于摘要继续新阶段的任务。这就好比开长会时，让助理把前面两个小时的讨论浓缩成一页纪要，后面大家就看着纪要接着聊，效率翻倍。

另一个手段是控制“信息输入”。不要让 Agent 一上来就把整个仓库读一遍，而是引导它先看目录结构，再按需打开文件。很多时候，给 Agent 一半的杂音信息，它会花三倍的 token 去筛选和纠偏。合理的方式是在任务描述里明说“先看 src 目录下的文件，不要读 node_modules 和构建产物”。

成本控制的思路还可以结合自定义 Agent。简单任务用轻量便宜的模型，复杂架构分析用能力强的大模型，通过配置不同的 agent 和 model 组合，可以在效果和成本之间找到平衡点。我在实践中发现，大部分代码审查、文档生成、格式化任务根本不需要顶级模型，用小一号的模型能把成本降一半以上，效果差别很小。

5. 我在实际使用中踩过的坑与排查方法

5.1 高频问题速查表

把我在使用过程中遇到过的典型问题整理成了一张速查表，按“现象—可能原因—解决办法”来看，排查效率会高很多：

这张表最想强调的其实是第一行。很多人遇到连接失败第一反应是换网络，但实际上八成是配置字段写错了，尤其是 model 字段的“供应商/模型名”组合形式，少写一个层级都会报错。

5.2 几个非常实用的避坑小技巧

第一条，给任务描述加验收标准。不要只告诉 Agent “把登录接口改成防重放校验”，而是要告诉它“改完之后跑 test/security 下的相关测试，必须通过才算完成”。有了验收标准，Agent 会自己循环执行直到满足条件，而不是改完代码就自我感觉良好地收工。

第二条，大改动之前先让它出计划。不要一上来就让它动大刀。你可以先要求 Agent 分析现状、列出改动点、预估影响范围，等你确认了方案之后再让它动手。这个“先计划后执行”的流程能悬崖勒马，避免方向错了白改一通。

第三条，在 AGENTS.md 里写清楚“禁止事项”。相比告诉它“你应该怎么做”，告诉它“绝对不能做什么”往往更能控制风险。比如“不允许修改 public 目录”“不允许执行删除命令”“不要动配置文件里的密钥字段”。这类硬边界会比一堆正向指导更有约束力。

第四条，API Key 别写进配置文件。虽然配置文件里可以存明文密钥，但一旦配置文件被同步到版本仓库或者发给别人，密钥就泄漏了。更稳的做法是让密钥从环境变量读取，配置里只填变量名。这个习惯在团队协作里尤其重要。

第五条，被 Agent 改崩了不要慌，用版本管理兜底。我一般操作前会让 Agent 只动当前分支，发现改坏了直接回退到上一次提交，再用git diff让 Agent 自己看这次的改动范围。把它纳入常规工作流之后，Agent 的自由度可以给得更大，反正错了也能低成本回滚。

5.3 团队落地和后续可以扩展的方向

如果团队里想要统一推广 OpenCode，有几个事最好提前做。第一，锁版本、统配置。把全局配置模板做成一份共享文件，包含模型选择、权限策略、常用自定义 Agent，所有人都用同一套初始配置，避免“一人一个样”的混乱。第二，把 AGENTS.md 纳入团队的文档规范，每个项目都必须有，并且和项目代码一起维护。第三，设计“先只读后写入”的入门流程，新成员第一次接触时，先只用只读模式跑几个审查任务，熟悉了再开放写权限。

单次执行模式在团队自动化里的潜力也很大。可以用它做一个“提交前自动审查”的钩子，代码准备提交时自动触发一个审查 Agent 跑一遍，发现问题就阻止提交或者给出提醒。这个流程不需要人全程盯着，Agent 在后台跑完把结果写进日志就行。长期下来，等于团队多了一个不知疲倦的代码审查员。

还有一点，OpenCode 的配置是可以直接纳入版本管理的，也就是说你完全可以把整套 Agent 配置、项目规范、自定义角色作为一个项目资产来维护。新项目初始化时直接复制这套模板，团队的人工智能协作规范就自然沉淀下来了。

最后分享一点我自己的体会。用 OpenCode 这类终端 Agent 和用 IDE 补全工具，最大的区别是思维方式的转变：它不是帮你打字的，而是需要你描述目标、设定边界、审查结果的协作者。我踩过几次“让它自由发挥结果改崩”的坑之后，慢慢养成了“先规划、再执行、最后审查”的习惯，这个习惯带进任何 AI 编程工具都适用。如果你第一次接触，别急着让它做复杂任务，先建一份 AGENTS.md、跑一个小任务、熟悉一下权限控制，再慢慢把它的能力放出来。相信我，一旦你适应了这种工作方式，就很难再回去了。