企业官网建设流程全解析

先从一个真实的场景说起。我在终端里改一个 Python 服务，突然想查一段正则为什么匹配不上，顺手打开浏览器登录 ChatGPT 又觉得太重，切到 IDE 里的 AI 插件又嫌上下文太乱。那时候我就在想，要是有一个工具能在命令行里直接跟我对话、能读懂当前目录的代码、还能直接改文件，那就省事太多了。后来我知道了 OpenCode，试了一晚上，第二天就把日常的 AI 编程辅助全迁了过去。所以这篇东西，就是想把 OpenCode 的安装与使用从头到尾讲清楚，让更多人少踩点坑。

OpenCode 是一个开源的 AI 编程助手，跑在终端里，主打轻量、快速、模型无关。它跟 Cursor、Cline 这类工具解决的是同一个问题，但思路完全不同。如果你平时用惯了 IDE 里的对话面板，第一次看到 OpenCode 的终端界面可能会觉得简陋，但用几天就会发现，这种“少即是多”的设计反而让 AI 辅助编程真正融入了日常开发流。

这篇内容适合三类人：一是每天和终端打交道的后端开发者，二是想尝试本地模型做编程辅助但不知道怎么接的人，三是被 Cursor 这类闭源工具的订阅费烦到想换开源的玩家。下面我会从工具定位、三种安装方式、模型接入、实战用法到问题排查，完整走一遍，希望能帮你少走弯路。

1. 先搞清楚 OpenCode 是什么，再决定要不要装

1.1 一个跑在终端里的 AI 编程助手

OpenCode 的核心形态是一个 TUI（Text User Interface）应用，也就是在终端里渲染出一个交互界面，有对话列表、消息流、文件 diff 预览，但全程不需要离开命令行。它跟纯粹的 CLI 工具（比如直接opencode "修复这个bug"然后等输出）还不一样，它有自己的交互界面，用方向键、回车、斜杠命令这套操作逻辑。

我第一次打开它的时候，界面让我想起终端里的邮箱客户端，左边是会话列表，右边是对话区，底部是输入框。第一次用的人可能有点懵，因为没有任何图形化的引导，但上手成本其实很低。常用的操作就几个：Ctrl+N新建会话、Ctrl+C中断输出、/呼出命令菜单、Shift+Tab在输入框和输出框之间切换焦点。这套交互在官方文档里有完整说明，但实际用下来，记住这几个核心键位就够了，其他都是锦上添花。

1.2 模型无关：一个客户端连接所有后端

OpenCode 最吸引我的一点，是模型无关的设计。它默认支持几十种模型供应商，包括 Anthropic 的 Claude、OpenAI 的 GPT 系列、Google 的 Gemini，也支持 Ollama 这类本地模型服务，还有它自己的控制台免费额度。

这意味着什么？意味着你不需要为某个特定的 AI 编程工具锁定模型，也不需要因为工具只支持特定厂商而被迫付费。你可以在同一个工具里随时切换：日常问简单问题用免费模型，写复杂重构用能力强点的模型，完全离线时用本地模型。这种自由度和传统 IDE 里那种“装插件再配 API Key”的模式很不一样。

模型无关的底层原因，是 OpenCode 把模型调用抽象成了一层协议。它支持 Anthropic 的 Messages API、OpenAI 的 Chat Completions API，也支持两者兼容的第三方中转服务。所有模型供应商都被拉平到同一个接口上统一处理，所以切换模型对用户来说就是一次按键的事，不需要改任何代码。

1.3 适合谁用，不适合谁用

这个我得说实话，OpenCode 不是所有人的菜。如果你不碰终端、只习惯在 Web 界面或完整 IDE 里操作，那它的学习曲线会让你有点难受。但如果你是那种已经在终端里用 Git、用 Vim、用各种 CLI 工具的人，OpenCode 几乎是零学习成本。

还有一个更适合的场景是多项目并行开发。因为 OpenCode 是跟着当前目录走的，你可以在~/project-a里启动一个会话，再在~/project-b里启动另一个，互相不干扰。相比 IDE 里那种项目切换的笨重感，这种方式自然得多。

2. 三种安装路径：命令行、桌面版、VSCode 插件

2.1 最快上手：一行命令装 CLI

OpenCode 的 CLI 安装方式很简单，官方提供了两种途径。一种是直接跑一键安装脚本：

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

这个脚本会自动检测系统架构（macOS 的 arm64 / x86_64，Linux 的对应架构，Windows WSL 环境），然后下载对应二进制并安装到用户目录下。安装完成后，脚本会提示你把 OpenCode 的可执行文件路径加入 PATH，通常是在~/.opencode/bin或类似目录下。如果你用的是 macOS，也可以直接用 Homebrew 安装：

brew install opencode

装完以后验证一下：

opencode --version

能看到版本号就说明装好了。这个验证步骤别省，我见过太多人装完直接跑opencode，结果命令找不到，又排查半天，最后发现是 PATH 没配好。

2.2 桌面版：不想碰终端的另一条路

如果你还是想有个窗口化的界面，OpenCode 也有桌面版。桌面版实际上是用 WebView 包了一层，把终端里的 TUI 界面搬到了独立的桌面窗口里，支持 macOS、Linux、Windows。它和 CLI 版共享同一个配置目录，也就是说你在桌面版里创建的会话，在 CLI 里也能看到，反之亦然。

安装桌面版的方式是去 OpenCode 的 GitHub Releases 页面下载对应的安装包。macOS 用户下载.dmg，Windows 用户下载.exe或.msix，Linux 用户下载.AppImage或.deb。下载后正常安装就行。

不过说实话，我用了一段时间桌面版，最后还是回到了终端版。原因是桌面版本质上是同一套代码在窗口里运行，却额外占用内存和渲染资源，而它带来的唯一好处就是“看起来像个桌面应用”。如果你不是特别需要独立窗口，直接用终端版反而更流畅。

2.3 VSCode 扩展装不上、搜不到怎么办

很多人在 VSCode 的扩展市场里搜索 OpenCode，会遇到两个问题：搜不到、或者搜到了但有多个同名扩展不知道选哪个。

这里要说清楚一点：OpenCode 官方在 VSCode 市场里其实有扩展，但名字不一定是 OpenCode 本身，有可能叫 “OpenCode AI” 或者由社区维护。更靠谱的做法是去官方文档或 GitHub 页面找扩展链接，而不是在市场里盲目搜索。有些时候，搜索不到是因为 VSCode 的扩展源设置问题，可以检查一下是否启用了正确的市场源。

安装完扩展后，VSCode 里会多一个 OpenCode 的面板，可以直接在 IDE 里打开终端界面，也可以把当前选中的代码直接发送到 OpenCode 会话里。这个面板本质上还是在调 CLI，所以前置条件仍然是命令行版已经安装成功。换句话说，如果你在 VSCode 里打开 OpenCode 面板却报错找不到命令，十有八九是 CLI 没装好或 PATH 没配好，跟扩展本身没关系。

2.4 安装完怎么验证

装完以后别急着用，建议先跑一个最简单的命令确认基础功能正常：

opencode run "说一句你好"

这会以非交互模式跑一次对话，如果配置了可用的模型，它会直接返回对话内容。如果没有配置任何模型，它会提示你登录或添加模型供应商。这一步能很快定位是安装问题还是模型配置问题。

3. 模型接入：从控制台免费额度到 Ollama 本地推理

3.1 控制台免费额度怎么开通

OpenCode 有一个官方的控制台服务，提供免费模型额度。这个免费层对初次体验的用户非常友好，不需要绑信用卡，只需要一个 GitHub 账号登录即可。

具体操作是：先运行opencode进入交互界面，然后用方向键选中 “Console” 或类似选项，按回车。它会弹出一个链接，让你在浏览器里完成授权登录。登录成功后，CLI 会自动获取对应的凭证，然后你就可以用控制台提供的免费模型了。

使用的时候有个细节需要注意，控制台 provider 提供的免费额度是有限制的，比如每天的消息数或每分钟的并发数。如果你只是日常小问题咨询，基本够用；但如果用来跑大型代码重构，额度很快就见底了。另外，控制台的免费额度只能在 OpenCode 应用内使用，不能通过其他客户端或 API 方式调用，这点我们要在下一节详细说。

3.2 那个常见报错：“free tier can only be used from within opencode”

这个报错我在网上看到很多人遇到，完整信息是：

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

我第一次遇到这个报错时也很困惑，明明就是在 OpenCode 里发起的请求，怎么会提示“只能在 OpenCode 内使用”？后来排查了半天才搞明白，问题出在模型调用的源头。

这个报错的意思是：当前请求被识别为来自 OpenCode 之外的第三方客户端。最常见的触发场景是，你在其他工具（比如另一个 AI 客户端、脚本或程序）里配置了console作为模型提供方，然后通过 OpenAI 兼容接口或 Anthropic 兼容接口去调用 OpenCode 控制台的服务。控制台服务检查到调用来源不是 OpenCode 自身，就拒绝了请求。

还有另一种触发场景，是在 OpenCode 内使用了自定义的 API Base URL，指向了控制台服务。也就是说，你通过opencode客户端发送请求，但客户端配置的是兼容接口地址，导致服务端认为这不是原生调用。解决办法是在模型配置里直接选择opencode作为 provider，而不是手动填写baseURL。

如果你的确是想在 OpenCode 内部使用免费额度，确认方法其实很简单：在交互界面的模型选择器里，选中 Console 提供的模型，不要手动改配置文件里的baseURL。如果是想在 OpenCode 之外用其他模型，老老实实去申请对应厂商的 API Key，别打控制台免费额度的主意。

提示：遇到 provider 报错时，第一反应应该去看opencode.toml或opencode.json里的模型配置，而不是怀疑是工具本身的 bug。绝大多数模型访问问题都出在 provider 配置环节。

3.3 连接 Ollama 跑本地模型

如果你对数据隐私要求高，或者希望完全离线使用，OpenCode 连接 Ollama 是个很好的方案。Ollama 是一个本地模型运行工具，支持 Llama、Qwen、Mistral、Granite 等主流开源模型，把模型下载到本地后用一条命令就能提供 OpenAI 兼容的 API 服务。

OpenCode 连接 Ollama 的方式有两种：

第一种是直接在模型选择器里找 Ollama。如果你本机已经装了 Ollama 并拉取了模型，OpenCode 会自动检测到http://localhost:11434上的 Ollama 服务，并把可用的本地模型列出来，选择就能用。

第二种是手动在配置文件里指定。打开 OpenCode 的配置文件（后面会说在哪里），添加类似下面的内容：

[model_providers.ollama] name = "Ollama" base_url = "http://localhost:11434/v1" api_key = "ollama"

添加后重启 OpenCode，在模型选择器里就能看到 Ollama 下的模型了。注意，Ollama 默认不校验 API Key，但 OpenCode 要求配置里必须有这个字段，所以随便填一个就行。

实际体验下来，本地模型的编程能力跟 Claude、GPT 仍然有差距，但胜在免费、离线、数据不出本地。对于代码解释、正则生成、简单脚本这类轻量任务，本地模型完全够用。我在没有外网的环境里用 Gemma 或 Granite 做日常咨询，体验已经可以接受了。关于 Granite 的接入方式，也是走 Ollama 这条路径，先在 Ollama 里拉取 Granite 模型，然后回到 OpenCode 选择即可。

3.4 手动配其他模型供应商

控制台免费额度和 Ollama 只是两种最省事的方案。如果你想用自己的 Claude、GPT 或 Gemini API Key，配置方式也很清晰。运行opencode后按E键（或/models）打开模型配置界面，按提示输入 API Key 即可。OpenCode 会自动识别密钥格式，判断是哪个供应商的 Key，然后把对应的模型列表加载出来。

如果你想多账号切换，比如公司一个 Key、个人一个 Key，可以开两个配置文件，通过环境变量OPENCODE_CONFIG指定使用哪一个。团队协作时，也可以把配置文件提交到 Git 仓库，让大家统一模型参数，但注意不要把 API Key 提交上去。

4. 从闲聊到真干活：AGENTS.md、Skills 与对话归档

4.1 AGENTS.md：让 AI 懂项目规矩

如果说模型是 OpenCode 的大脑，那 AGENTS.md 就是 AI 的项目说明书。这个文件放在项目根目录，用 Markdown 编写，OpenCode 在每次会话启动时会自动读取它，并把它作为上下文的一部分传给模型。这样模型就能了解项目的结构、代码风格、构建命令、注意事项等信息，给出的建议也更有针对性。

为什么这个文件很重要？因为模型对项目的理解完全取决于上下文。你不告诉它这是一个用 FastAPI 写的服务，它可能默认按 Flask 的写法给建议；你不告诉它项目里有自动生成的 proto 文件不能动，它可能某次“好心”帮你改掉。而 AGENTS.md 正是用来解决这些问题的。

我的做法是，每个项目维护一个精简的 AGENTS.md，包含四个部分：

# 项目概述 这是一个内部数据平台的后端服务，使用 FastAPI + SQLAlchemy，Python 3.11。 # 常用命令 - 本地启动：uvicorn app.main:app --reload - 运行测试：pytest tests/ -x -q - 代码格式：ruff check . # 项目约定 - 禁止修改 migrations/ 目录下的已有迁移文件 - 所有接口必须使用 Pydantic 做请求校验 - 新增依赖需要通过 poetry add 添加 # 已知约束 - 单机部署，暂不考虑分布式 - 数据库使用 PostgreSQL 13，避免使用 JSONB 字段

写完后放到项目根目录，OpenCode 的每次会话都会自动带上这份说明。效果非常明显：在不写 AGENTS.md 之前，AI 给出的代码经常不符合项目风格，写了之后，第一次生成的代码就基本能直接进 PR。

4.2 Skills：给 AI 造趁手的工具

Skills 是 OpenCode 的一个特色功能，你可以把它理解成给 AI 装配的技能包。每个 Skill 是一个目录，里面有一个SKILL.md文件，描述这个技能什么时候用、怎么用；还可以附带脚本文件，让 AI 在执行任务时可以调用这些脚本。

举个例子。我经常需要给新写的模块加单元测试，就写了一个 Skill 专门干这个。SKILL.md 内容大致是：

--- name: add-tests description: 为指定 Python 模块生成 pytest 单元测试 --- # Add Tests Skill 当用户希望为某个模块添加测试时使用此技能。 ## 步骤 1. 读取用户指定的模块文件，分析其类和函数 2. 识别需要测试的公共接口 3. 生成 pytest 测试文件，保存到 tests/ 目录下 4. 运行 pytest --cov 验证测试覆盖率 ## 注意事项 - 测试代码风格遵循项目现有约定 - 不测试第三方库的行为 - 测试用例尽可能覆盖边界条件

写完这个文件后，放在~/.config/opencode/skills/add-tests/目录下（不同系统路径略有差异），然后在 OpenCode 里输入/add-tests app/services/user_service.py，AI 就会按照 SKILL.md 里的流程去执行任务。这个机制把“每次对话都要重复交代一遍要求”变成了“一句话调用完整流程”，非常实用。

除了自己写，OpenCode 社区也有一批现成的 Skill 可以直接下载使用。安装方式很简单，通常是把对应的 Skill 目录克隆下来，放到 OpenCode 的 skills 目录里就行。社区里比较热门的 Skill 包括生成提交信息、代码审查、SQL 优化、Git 冲突解决等。

4.3 代码改动怎么落盘，归档对话存在哪

OpenCode 不只是聊天工具，它能直接改代码。当 AI 给出修改建议后，你可以按a键接受全部改动，或者按Tab在改动块之间切换，逐块审查是否接受。接受后，改动会直接写入文件。这种逐块确认的机制比 AI 直接改全部要安全得多，我在实际使用中强烈建议用这种方式。

但也要提醒一点：OpenCode 的代码修改是基于当前文件内容和模型生成结果做的补丁式应用，遇到文件特别大或者模型输出被截断时，偶尔会出现应用失败的情况。碰到这种问题，不要慌，让模型重新生成，或者手动复制改动内容。

关于归档对话，很多人问过“OpenCode 归档后去哪了”。默认情况下，所有对话记录会存在本地的 SQLite 数据库里，具体位置在配置目录下。macOS 是在~/.local/share/opencode/，Linux 同理。如果你在那个目录里看到了类似opencode.db的文件，那就是对话存档。OpenCode 本身没有提供官方的一键导出功能，但你可以用 SQLite 浏览器打开这个数据库文件查看已有会话。如果你删了配置文件或数据库文件，历史会话就彻底没了，所以重要信息最好及时复制到项目笔记里。

5. 用了一段时间后的几个坑与建议

5.1 关于数据安全的几个原则

用 OpenCode 这类工具，数据安全是一个绕不开的话题。我的建议是分三层去考虑。

第一层，项目代码本身的敏感性。如果你的项目涉及非公开业务逻辑，尽量不要使用外部模型服务，或者至少确保公司允许把代码片段发送给对应模型厂商。第二层，本地模型方案。对保密要求高的项目，本地跑一个开源模型是最稳妥的，代码根本不出本机。第三层，配置信息保护。OpenCode 的配置文件里会保存 API Key 等敏感信息，注意文件权限要设置成仅当前用户可读写，不要因为追求方便把它提交到公共仓库。

5.2 终端卡顿和输出丢失

OpenCode 的 TUI 界面在大多数终端下表现不错，但有两个场景会出问题。第一个是终端编码问题，如果终端字符集不支持某些特殊符号，界面里可能会出现乱码，这种情况把终端的编码切到 UTF-8 就行。第二个是输出丢失，当模型生成长文本时，如果网络不稳定或服务端响应超时，界面可能突然空白或者只显示一部分。这种时候先看是不是网络问题，如果不是，重启 OpenCode 一般能解决。

还有一个容易被忽略的性能问题：OpenCode 默认会把整个项目的文件索引加载一遍来计算上下文。如果你在一个很大的 monorepo 仓库里使用，首次启动可能会明显卡顿。官方提供了一些配置项来控制扫描范围，比如忽略node_modules、dist、.git等目录，能显著提升启动速度。

5.3 一套比较顺手的日常工作流

最后分享一下我目前的日常使用流。每天早上到工位，我会先开一个 OpenCode 会话，把当天的任务列表粘过去，让 AI 帮我拆解成步骤，同时写好 AGENTS.md 让 AI 了解最新状态。开始写代码时，遇到不确定的 API 就随手选中代码，发送到 OpenCode 询问。写完一个模块后，直接让 AI 生成测试，再用预置的 Skill 跑一遍代码审查。整个过程中完全不离开终端。

这个流程最妙的地方在于，它可以跟 Git 工作流无缝衔接。对话摘要可以存在 Git message 里，遇到问题可以先看历史会话记录，不需要翻聊天记录。相比于 IDE 里装一堆插件，这种极简、可组装的方式反而更适合我。

我也理解不是所有人都愿意把日常工作都迁到终端里，但我建议给 OpenCode 一个机会。先用控制台的免费额度体验两天，觉得顺手了再接入自己的 API Key，一步步来。它不一定能取代 Cursor 或 Copilot，但在某些开发场景下，效率提升是很明显的。

装一个试试吧，成本很低，但可能改变你的开发习惯。