企业官网建设流程全解析

最近我把主力 AI 编码助手从网页端迁到了终端里的 OpenCode，用下来最直观的感受是：它把"AI 对话改代码"这件事拉回到了开发者最熟悉的编辑器/终端环境里，不需要来回复制粘贴，模型也接得干净利落。这篇就围绕 OpenCode 安装、模型配置、Skill 扩展、局域网 serve、常见报错这几个高频问题，把我在实际部署和使用中踩过的坑、验证过的方案一次性讲清楚。

如果你准备在 Linux/macOS/Windows 上用开源 CLI 工具接入 Codex、Ollama、Granite 这类模型，或者想让局域网内的其他设备也能调起 OpenCode 的能力，这篇应该能帮你省掉不少查文档的功夫。

1. 先搞清楚 OpenCode 是什么，它的定位和优势在哪里

很多人第一次听到 OpenCode，会下意识把它和 Cursor、Continue 这类 IDE 插件混为一谈。其实它的核心形态是一个跑在终端里的 AI 编码代理，你可以在任意项目目录下启动它，通过自然语言让 AI 读取代码、修改文件、执行命令，甚至是批量重构。它更接近 Claude Code 或者 Codex CLI 这类工具，而不是一个"能聊天的编辑器插件"。

1.1 终端 AI 助手和 IDE 插件到底有什么区别

IDE 插件的思路是"在编辑器里给你一个对话窗口"，AI 拿到了你的选区、当前文件、诊断信息之后给建议，你需要手动接受 diff。OpenCode 的思路是"在终端里给你一个完整的 AI 代理"，它自己就能操作文件系统、运行测试、查看 git diff，你只需要告诉它目标，它会自己规划步骤并执行。

举个例子，我经常让它做这样的事："把这个项目的错误处理统一改成自定义异常，然后跑一遍测试告诉我哪里挂了"。在IDE插件里，你需要手动指定文件、手动应用补丁；在 OpenCode 里，它自己会搜索相关代码、修改文件、执行测试命令，然后回报结果。这种差异在重构老项目时尤其明显。

1.2 为什么我最终选择了 OpenCode

选型时我对比过几款工具，最终留下 OpenCode 有四个原因。

第一，开源且本地优先。配置文件和会话记录都是本地文件，代码仓库默认不会上传到某个私有的云服务。对在意代码合规和隐私的团队来说，这一点能省去不少流程上的麻烦。

第二，模型接入是真的灵活。它内置支持多种 provider，既能连 OpenAI 的 Codex、也能连 Ollama 上的本地模型，还有 IBM Granite 这类开发者模型。你可以一条命令切换，不用在不同工具之间来回跳。

第三，操作效率确实高。它在终端里提供了一套快捷交互：用@引用文件、用#引入终端输出、用/model切换模型、用/sessions恢复历史会话。用习惯了之后，整个工作流可以完全不离开终端。

第四，有独立的桌面版和编辑器扩展。不在终端工作的人也能用，Visual Studio Code 扩展和 JetBrains 插件都有，PyCharm、IDEA 用户同样能接上。

2. 安装 OpenCode：从命令行到桌面端一次性搞定

OpenCode 的安装方式很多，macOS、Linux、Windows 都有对应渠道。我建议按用途来选择安装方式：主要用终端的走包管理器；想要图形界面的直接装桌面版；需要在 IDE 里用的就装对应插件。

2.1 macOS、Linux、Windows 三种安装方式对比

macOS 上最省事的方式是 Homebrew：

brew install opencode

装完之后在任意项目目录里输入opencode就能启动。这条命令会安装最新稳定版，后续升级用brew upgrade opencode就行。

Linux 上官方推荐用安装脚本：

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

脚本会检测系统架构，下载对应的二进制文件到~/.opencode/bin，并在 shell 配置里追加 PATH。执行完后重开终端，运行opencode --version能看到版本号就说明没问题。

Windows 上可以用 Scoop：

scoop install opencode

也可以直接从 GitHub Releases 页面下载 exe 文件，解压后把路径加入系统 PATH。我个人更推荐 Scoop，因为后续scoop update opencode一行命令就能升级。

如果你不想用包管理器，官方也提供了 npm 安装方式：

npm install -g opencode-ai

我实测下来 npm 包和二进制版本功能一致，适合已经把 Node.js 环境作为标配的开发者。

2.2 安装后的初始化配置

第一次运行opencode时，它会询问你使用哪个模型服务商。这里先不用急着选，因为后面随时可以改。你只需要确认一件事：你的 API 密钥从哪里来。

如果你用的是 opencode 官方提供的 Go 订阅计划，可以直接在交互界面选择opencode作为 provider，然后回车进入登录流程。如果你有自己的 Codex、OpenAI 或者其他模型 API 密钥，选择对应的 provider，把密钥填进去即可。密钥保存位置一般在~/.local/share/opencode/auth.json（Linux/macOS）或者%APPDATA%\opencode\auth.json（Windows），手动编辑这个文件也可以更新密钥。

注意：配置完成后建议立刻运行一次opencode发一句"你好"，确认模型能正常响应。如果这一步就报错，后面所有的功能都会受影响。常见原因基本集中在 provider 选择错误、密钥填错、网络不通这几类。

2.3 桌面版、VS Code 插件和 JetBrains 插件

不想整日泡在终端里的朋友，可以直接装 OpenCode 桌面版。桌面版内置了编辑器界面，左侧是文件树，右侧是会话面板，用起来很像一个轻量级 AI IDE。下载地址在官网首页就能找到，Windows 和 macOS 都有对应的安装包。

VS Code 用户直接在扩展市场搜索opencode，找到官方扩展安装即可。如果搜不到，大概率是扩展市场来源设置的问题——VS Code 默认会从 Microsoft Marketplace 拉取扩展，你可以检查一下是否被切换到了 Open VSX 或者其他来源。

JetBrains 系（IDEA、PyCharm、GoLand 等）则是在插件市场搜索opencode，安装后会在右侧工具窗口出现一个 OpenCode 面板，可以直接在 IDE 里对话、引用项目文件。这个插件对于习惯 JetBrains 重构功能的老用户来说很顺手，AI 改动代码后可以直接使用 IDE 的 diff 视图审阅。

提示：如果你在使用 Cursor，也尝试搜过 OpenCode 扩展但找不到，这是正常的。Cursor 有自己的一套扩展体系，去它的扩展市场搜不到 OpenCode 是预期行为，直接用 OpenCode 官方桌面版或者独立 VS Code 就行。

3. OpenCode 核心使用姿势：模型切换、会话管理与 Skill 扩展

安装只是开始，真正影响效率的是日常操作方式和扩展机制。这一节讲几个高频动作：怎么切换到合适的模型、怎么管理历史会话、怎么通过 Skill 让 OpenCode 具备自定义能力。

3.1 进入第一个会话：引用文件、引入终端输出

在项目根目录启动opencode后，你会进入一个交互式 TUI 界面。最下面一行是输入框，你可以直接输入自然语言指令。这里有几个非常重要的快捷键和语法。

使用@符号可以引用具体文件。比如我输入"看看@src/main.py里的逻辑，帮我优化一下"，它会精准读取该文件作为上下文。这个用法在改动大型项目的局部模块时特别好用，不用把整个仓库都塞给模型，既省 token 又减少干扰。

使用#符号可以引入终端输出。比如你刚跑完一条命令报错了，直接在输入框里输入#加上错误信息，它会自动把最近一次终端输出作为上下文。这样你描述问题的时候就不用再手动复制大段报错文本了。

如果你临时改主意想换模型，输入/model会弹出模型列表，上下键选择、回车确认。整个切换过程是热切换，不需要重启会话，当前上下文会保留。这个我实测在对比模型效果时非常方便，同一个任务在 Codex 和 Granite 之间来回切，很快就知道哪个更适合手头的代码风格。

3.2 历史会话存在哪，怎么找回归档的对话

用过一段时间后，你会积累很多历史会话。如果你找不到之前的对话在哪儿，先别急着开新会话。在 OpenCode TUI 里输入/sessions，会列出所有历史会话记录，按时间排序，选中任意一条就能恢复上下文继续对话。

底层存储位置也有规律：Linux/macOS 在~/.local/share/opencode/目录下，Windows 在%APPDATA%\opencode\目录下。里面会有 sessions 目录，每个会话一个 JSON 文件，包含消息记录、文件改动记录、时间戳等信息。如果你需要备份或者迁移，直接把整个目录拷走就行。

注意：目录里通常还有 storage 目录，用于存放消息附件和其他临时文件。我建议定期备份 sessions 目录就够了，storage 目录比较占空间，不需要全量打包。

3.3 Skill 怎么安装、怎么自己写一个

Skill 是 OpenCode 很能打的一个扩展机制，它允许你通过自定义指令集让 AI 掌握特定的工作流程。比如你可以写一个"提交信息生成 Skill"，让 AI 按照你团队的规范生成 git commit message；也可以写一个"代码审阅 Skill"，让它每次都按照固定维度检查代码。

Skill 的存放位置是项目内的.opencode/skills/目录。每个 Skill 就是一个子目录，里面包含一个SKILL.md文件。这个文件的格式不复杂，示例：

--- name: git-commit description: 根据 git diff 生成符合团队规范的提交信息 --- 当用户要求生成提交信息时，执行以下步骤： 1. 运行 git diff 查看变更 2. 识别变更类型（feat、fix、refactor、docs、test） 3. 输出规范格式：<type>(<scope>): <subject>

保存后，回到 OpenCode 会话中输入"生成提交信息"，它就能根据这个 Skill 的指示来处理。Skill 里还可以包含脚本文件，OpenCode 会调用脚本完成更复杂的自动化操作。我还尝试过从社区下载别人写好的 Skill 放到对应目录，效果立竿见影。GitHub 上已经有不少现成 Skill 仓库，比如 oh-my-opencode 这类聚合项目，下载后解压到.opencode/skills/即可。

提示：写 Skill 时有一个容易踩的坑——description 字段要尽量描述"什么场景下触发"，而不是"它能做什么"。OpenCode 是根据语义匹配来调用 Skill 的，description 写得越贴近用户的自然语言，触发准确率越高。

3.4 配置 opencode 2.0 版本的新特性

如果你用的是 OpenCode 2.0 之后的版本，配置文件的组织方式和旧版有些不同。新版主配置集中在opencode.json，支持按项目覆盖。比如你可以在项目根目录放一个opencode.json，覆盖全局配置里的模型参数、Skill 启用列表、环境变量等。

一个典型的配置文件长这样：

{ "$schema": "https://opencode.ai/config.json", "model": "gpt-5", "provider": { "ollama": { "models": [ { "name": "granite3-dense:8b", "baseURL": "http://localhost:11434/v1" } ] } } }

这个配置的意思是：默认模型用 gpt-5，同时自定义了一个名为 ollama 的 provider，里面接入本地的 granite3-dense:8b 模型。配置完成后，在 TUI 里用/model切换，就能看到这个本地模型。新版对 provider 的配置灵活度很高，这也是它能同时接云端模型和本地模型的根本原因。

4. 模型接入进阶：Go 订阅、Codex、Ollama 与 Granite 的完整接法

OpenCode 真正让人舒服的地方在于模型接入的灵活性。你既可以用官方订阅的托管通道，也可以带上自己的密钥接入 Codex，还可以在完全离线的环境里接 Ollama 上的本地模型。这一节我把自己试过的几种接法按场景拆开讲。

4.1 opencode go 订阅计划怎么用

如果你不想分别购买多个模型厂商的 API，直接用 opencode 官方的 Go 订阅计划会比较省心。它相当于一个聚合通道，订阅之后你不需要关心底层具体走了哪个模型的计费，只管在 OpenCode 里切换模型就行。

使用方式分两种。第一种是纯登录方式：在 OpenCode 的 provider 里选择 opencode，然后根据提示在浏览器里授权登录。第二种是密钥方式：在 opencode 官网的账户后台生成 API 密钥，然后把密钥填入 auth.json 或者环境变量OPENCODE_API_KEY中。两种方式我都试过，稳定性和速度没有明显差别，看你习惯哪种。

对于已经买了订阅但不知道怎么连接的用户，我建议先检查密钥是否写对了位置。在终端里运行：

echo $OPENCODE_API_KEY

如果输出为空，说明没有设置环境变量。用登录方式的话，直接重新在 TUI 里选 provider 走一遍授权流程，一般两分钟内能解决。另外，Go 订阅计划里可以接入 Codex 模型，选模型时注意不要选成旧版 Codex 的 experimental 通道，选“codex”类目下的正式模型更稳定。这个细节在社区里经常被问，我一开始也踩过，切换到正式通道后就再没报错过。

4.2 局域网访问：opencode serve 的正确用法

OpenCode 的 HTTP 服务模式非常适合局域网内共享能力。比如你有一台办公用的 Linux 服务器配置了模型通道，其他同事的电脑可以通过局域网访问这台服务器上的 OpenCode 接口，不用每台机器都配密钥。

启动局域网服务的方式是：

opencode serve --hostname 0.0.0.0 --port 4096

默认情况下，opencode serve只监听 127.0.0.1，也就是只能本机访问。要支持局域网访问，必须指定--hostname 0.0.0.0。启动后，其他设备可以通过http://<你的IP>:4096访问接口，在浏览器里能看到一个简单的前端页面，也可以用支持自定义 provider 的客户端（比如 CC Switch）指向这个地址。

如果你希望服务在后台常驻，我习惯用 systemd 或者 pm2 托管。以下是一个 systemd 服务文件示例：

[Unit] Description=OpenCode HTTP Server After=network.target [Service] ExecStart=/usr/local/bin/opencode serve --hostname 0.0.0.0 --port 4096 Restart=always User=<你的用户名> [Install] WantedBy=multi-user.target

注意：把服务暴露到局域网意味着同一网段的其他机器都能访问。如果你的网络环境里有不信任的设备，建议在服务前面加一层简单的访问令牌校验，不要让端口裸奔。

4.3 用 CC Switch 连接 opencode 再连接 ollama

CC Switch 是一个模型切换工具，很多人喜欢把它和 OpenCode 串起来用，做成"本地模型统一入口"。实际链路是：CC Switch 作为客户端，将请求转发给opencode serve暴露的接口，再由 OpenCode 路由到 Ollama 上的本地模型。这样的好处是，你的前端工具只需要配一个自定义 provider，后端模型想换就换。

具体配置分两步。第一步，在 OpenCode 的配置里添加 Ollama provider，确保 Ollama 的模型能通过 OpenCode 正常调用。第二步，在 CC Switch 里新增一个自定义 Provider，地址填http://<OpenCode所在机器的IP>:4096，协议类型选 OpenAI 兼容格式，模型名填你在 OpenCode 里配置好的模型名。保存后，在 CC Switch 里选中这个 Provider，就能把请求打到 OpenCode，最终落到 Ollama 的本地模型上。

这一步我踩过比较多的问题是"连上了但模型一直报 404"。排查思路是先确认 OpenCode 侧能不能正常调用 Ollama 模型：

opencode run "hi" --model ollama/granite3-dense:8b

如果这条命令能正常返回，说明 OpenCode 到 Ollama 的链路是通的。此时再去 CC Switch 里检查模型名是否和 OpenCode 配置里的模型名完全一致。注意，CC Switch 侧填的模型名不是 Ollama 里的原始模型名，而是 OpenCode 的 provider 配置中定义的模型 name，很多人在这里写错。

4.4 完全本地化：OpenCode 接 Ollama 和 Granite

如果你对数据隐私比较敏感，或者有些代码根本不适合发给云端模型，那就要走完全本地化的路线。OpenCode 接 Ollama 是目前最成熟的本地方案。以 IBM Granite 为例，Granite 是 IBM 开源的代码生成模型，在 Ollama 上可以直接拉取：

ollama pull granite3-dense:8b

拉取完成后，在 OpenCode 的opencode.json中配置 Ollama provider：

{ "provider": { "ollama": { "baseURL": "http://localhost:11434/v1", "models": [ { "name": "granite3-dense:8b", "aliases": ["granite"] } ] } } }

配置完成后，启动 OpenCode 并切换到ollama/granite3-dense:8b模型，就能在没有外网的情况下完成代码生成、解释、重构等任务。本地模型的速度完全取决于你的机器算力。我实测 8B 模型在 32GB 内存的 M 系列芯片上响应很流畅，日常改 bug 完全够用；如果做大规模重构，建议上更大的模型。

提示：本地模型和云端模型在使用体验上的差距，主要在指令遵循和复杂逻辑推理上。简单任务（生成单函数、解释代码、写测试用例）本地 8B 模型表现很好；跨多文件的深层重构，仍然是云端大模型更稳。我的习惯是"日常简单操作走本地，大型重构走云端"，两个通道在 OpenCode 里切换模型也就几秒钟的事。

5. 高频报错排查：从 free tier 报错到模型列表为空

使用过程中难免会遇到一些报错，尤其在你尝试把 OpenCode 接入到其他工具、或者配置自己的 provider 时。下面几个问题是社区热搜里出现频率最高的，我把原因和解决思路整理出来。

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

这个报错是很多人在用 CC Switch 或其他自定义客户端连接 OpenCode 时遇到的。报错的字面意思是：opencode 的免费额度只能在 OpenCode 客户端内部使用。也就是说，当你使用opencode serve或某种外部通道去调用 opencode 自带的免费模型时，服务端会拒绝请求，因为免费通道只允许在官方客户端内使用。

出现这个报错后，先不要慌。你需要确认自己是不是在用 opencode 官方免费模型作为 provider。如果你是通过外部工具（比如 CC Switch）调用 opencode serve 的接口，而 OpenCode 内部使用的又是 opencode 的免费通道，那这个报错是预期行为，官方就是不允许这样转发使用。解决办法有两个方向：一是换用你自己的 API 密钥接入其他 provider（比如 OpenAI、Codex），然后通过 serve 共享；二是订阅 opencode 的 Go 计划，用付费通道替代免费通道。付费通道不受这个限制，可以正常被外部客户端调用。

注意：如果只是本地使用 OpenCode TUI 或桌面版，几乎不会遇到这个报错。一旦你开始做局域网共享或者让其他工具来调 OpenCode 的接口，就必须检查模型通道的性质。

5.2 桌面版选择模型那里一个模型也没有了

有用户反馈说打开 OpenCode 桌面版，选择模型的下拉列表是空的。根据我排查的经验，大概率是以下三类原因之一。

第一，配置文件被写坏了。桌面版会读取全局的opencode.json，如果 JSON 格式错误或者 provider 配置缺失，模型列表就加载不出来。排查方式是打开终端，在任意目录下运行opencode，看看 TUI 里能不能正常列出模型。如果 TUI 也是空的，问题几乎可以确定在配置上。

第二，认证失效。如果你使用的是需要登录授权的 provider（比如 opencode 官方通道），token 过期之后模型列表会加载失败。桌面版侧重新登录一次即可，或者在 auth.json 里更新密钥。

第三，Go 订阅计划到期或没有绑定密钥。Go 计划欠费/到期之后，桌面端会呈现"模型列表空"的现象，但在终端里往往会有更明确的报错信息。建议先跑一遍终端版，把具体报错记下来，再回桌面版处理。

5.3 模型切换时提示 provider 未配置

在 TUI 里输入/model切换模型时，偶尔会遇到某个模型无法选择、提示 provider 未配置的情况。这通常是因为模型对应的 provider baseURL 没有写全。例如你只配置了模型名，却没有配置 baseURL，OpenCode 就不知道要把请求发到哪里。

解决办法是打开opencode.json，检查每个 provider 是否都有完整的baseURL和模型列表。特别是自定义本地模型时，baseURL一定要写对，Ollama 的默认地址是http://localhost:11434/v1，如果你改了端口，这里也要同步改。另一个容易忽略的是模型别名，如果你在配置里加了aliases，在 TUI 里切换时要使用别名而不是原始模型名。我不止一次在切换本地模型时发现"找不到模型"，最后检查都是 aliases 和实际输入不一致。

5.4 局域网客户端连接超时、页面打不开

局域网访问opencode serve时常见的症状是：本机能访问，别的电脑访问不了。优先检查两个地方。一是监听地址是否真的绑到了0.0.0.0，很多人在启动时漏了这个参数，服务只对本机开放。二是有没有防火墙拦截 4096 端口，Linux 上尤其常见。

sudo ufw allow 4096/tcp

如果开启了防火墙，先放行对应端口再试。另外一点，跨设备访问时建议直接用 IP 地址而不是主机名，因为有些内网环境下主机名解析不稳定。我之前在办公网里就遇到过每次都解析超时的情况，换成 IP 后立刻正常。

5.5 常见问题速查表

6. 我的一些个人经验和最后想说的

实际操作中我发现，OpenCode 这类终端 AI 代理工具，真正提升效率的不是它支持多少个模型，而是"会话可恢复、文件可引用、Skill 可扩展、服务可共享"这套完整的工作流。我现在每天的工作模式已经固定下来：日常小改动用本地 Granite 模型快速跑一遍，遇到大重构切换到 Codex 或云端模型，通过/sessions随时恢复昨天没聊完的上下文。这个过程完全在终端里完成，不打断编码节奏。

最后分享一个小技巧：在配置 Skill 的时候，不要贪多，先按自己团队最痛的一两个流程写起。比如我们最先写的"commit 信息生成"，生效后紧接着写了"代码审阅"。每跑通一个 Skill，OpenCode 的可用性就上一个台阶。相对于不停地研究新功能，把已有的几个高频能力打磨稳定，实际收益更大。这个经验是从我自己踩坑中得来的，希望对你有用。