企业官网建设流程全解析

1. 为什么我又折腾回了终端里的 AI Coding Agent

OpenCode 是一个跑在终端里的开源 AI Coding Agent，能读你整个代码仓库、按指令改文件、加功能、重构模块，背后可以接 GPT、Claude、DeepSeek 这类模型。它适合谁？适合那些不满足于 IDE 里补全几行代码、想让 AI 真正理解项目结构再动手的开发者，尤其是手里有 Spring Boot、React、Angular 这类目录复杂、历史包袱重的老项目的人。

我最早用 Claude Code 的时候觉得挺顺手，但它闭源、按量计费、配置不够透明。后来看到 OpenCode 这个开源替代方案，CLI 形态、支持自定义模型通道、还能挂 oh-my-opencode 这类插件把 Prompt 模板和工程规则标准化，就决定认真搭一套。这篇就把我从安装到接入 TaoToken 统一 Key、启用 oh-my-opencode、跑通首次对话的完整过程写下来，配置文件可以直接复制，验证命令逐条给。

核心检索词先摆清楚：OpenCode 是什么——开源 AI Coding Agent 的 CLI 实现；能做什么——在终端里读仓库、改代码、跑模板任务；适合谁——想统一团队 AI 使用方式、又不想被单一闭源工具绑死的工程团队和个人。

2. 前置准备：TaoToken 统一 Key 与 API 通道

OpenCode 本身不绑定任何模型供应商，它通过配置里的 provider 和 baseURL 去请求模型。我选择用 TaoToken 作为统一通道，原因是它把多家模型的 Key 收敛成一个，切换模型只改一个 model 字段，不用每个供应商单独配环境变量。

你需要先拿到一个 API Key。登录 TaoToken 控制台，在 API Keys 页面创建一个新 Key，复制出来。这个 Key 后面会写进 OpenCode 的配置文件里。

注意：Key 只显示一次，创建后立刻保存到本地密码管理器或环境变量，别直接提交进 Git 仓库。

TaoToken 的 API 入口是https://taotoken.net/api，这个地址在配置里作为 baseURL 使用。模型对话、Coding Plan、控制台、API Keys、接入文档这些入口分别对应不同的使用场景，后面 CTA 部分我会按场景分流。

环境上你只需要：Node.js 18 以上、一个终端、一个能跑起来的代码仓库。我用的是 macOS + zsh，Linux 同理，Windows 建议用 WSL。

3. 安装 OpenCode 并写入 settings.json / config.toml 骨架

3.1 安装 CLI

OpenCode 的安装方式随版本有差异，常见的是通过 npm 全局安装或者官方脚本。我先用 npm 方式：

npm install -g opencode-ai

装完验证版本：

opencode --version

如果提示命令找不到，检查 npm 全局 bin 目录是否在 PATH 里：

npm config get prefix

把输出的路径加进~/.zshrc的 PATH，再source ~/.zshrc。

3.2 配置文件位置

OpenCode 读取配置有两个层级：全局配置在~/.config/opencode/下，项目级配置在仓库根目录的.opencode/下。项目级优先，适合给单个仓库定制模型和规则。

我建议先写全局配置，保证任何目录下都能跑起来，再在具体项目里覆盖。

3.3 settings.json 骨架

全局配置文件我放在~/.config/opencode/settings.json，内容如下：

{ "provider": { "taotoken": { "type": "openai-compatible", "baseURL": "https://taotoken.net/api", "apiKey": "sk-你的TaoToken密钥", "models": { "claude-sonnet": "claude-sonnet-4-20250514", "gpt-4o": "gpt-4o", "deepseek-v3": "deepseek-chat" } } }, "defaultModel": "taotoken/claude-sonnet", "promptsDir": ".opencode/prompts", "rulesDir": ".opencode/rules" }

几个字段说明：type用openai-compatible是因为 TaoToken 的 API 兼容 OpenAI 请求格式；baseURL就是前面说的入口地址；models里我把常用模型做了别名映射，切换时只改defaultModel。

3.4 config.toml 骨架

有些 OpenCode 版本或插件读 TOML 格式，我在项目根目录建了.opencode/config.toml：

[model] provider = "taotoken" name = "claude-sonnet" base_url = "https://taotoken.net/api" [agent] plan_enabled = true build_enabled = true [prompts] dir = ".opencode/prompts" [rules] dir = ".opencode/rules"

TOML 和 JSON 二选一即可，看你的 OpenCode 版本读哪个。我实测下来新版优先读 JSON，TOML 作为兼容保留。

3.5 用环境变量存 Key（更安全）

不想把 Key 写死在配置文件里，可以改成读环境变量：

export TAOTOKEN_API_KEY="sk-你的密钥"

然后 settings.json 里把apiKey改成"${TAOTOKEN_API_KEY}"。这样配置文件可以进版本库，Key 留在本地。

4. 启用 oh-my-opencode 与首次对话验证

4.1 oh-my-opencode 是什么

oh-my-opencode 不是一个官方统一项目，更多是社区或团队内部的一套模板集合。它的核心作用是把「怎么用 AI 写代码」标准化：提供 add-feature、refactor-module、fix-bug、write-tests、explain-code 这类 Prompt 模板，加上项目级规则（不允许随意改 public API、必须遵循现有目录结构、先分析再动手），让 AI 不乱改。

4.2 目录结构

我在项目根目录建了这样的结构：

your-project/ .opencode/ prompts/ add-feature.md refactor-module.md fix-bug.md write-tests.md rules/ coding-style.md safety.md config.toml

4.3 写一个 refactor 模板

.opencode/prompts/refactor-module.md内容示例：

# 任务：安全重构模块 ## 步骤 1. 先通读目标模块及其依赖，列出对外暴露的接口 2. 标记所有 public API，重构中不得改变签名 3. 按现有目录结构拆分，不新建顶层目录 4. 每改一个文件，说明改动理由 5. 输出改动清单，等待 review ## 约束 - 不删除任何测试文件 - 不修改配置文件 - 遇到不确定的地方先提问，不要猜

4.4 写一条安全规则

.opencode/rules/safety.md：

# 安全规则 - 禁止修改 public API 签名 - 禁止删除现有测试 - 禁止改动 CI/CD 配置 - 所有改动必须先分析再动手 - 输出必须包含改动文件列表

4.5 让 OpenCode 识别模板

在 settings.json 里已经配了promptsDir和rulesDir，OpenCode 启动时会自动加载。也可以用初始化命令生成骨架：

opencode init

它会扫描当前仓库，生成一个agents.md文件，相当于让 AI 先通读整个项目结构。

4.6 首次对话验证

先跑一个最简单的请求，确认链路通：

opencode run "列出当前项目的顶层目录结构，不要改任何文件"

如果配置正确，终端会流式输出模型返回的目录树。这一步只读不写，最安全。

确认通了之后，跑模板任务：

opencode run refactor-module

它会读取.opencode/prompts/refactor-module.md，套用模板，按规则执行，最后给你一份可 review 的改动清单。

4.7 验证请求链路

想确认请求真的走了 TaoToken，可以在 settings.json 里临时打开 debug 日志，或者用 curl 直接打一次 API：

curl -s https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-sonnet-4-20250514", "messages": [{"role": "user", "content": "ping"}] }'

返回里有choices字段就说明 Key 和通道都正常。这一步能帮你把「OpenCode 配置问题」和「Key/通道问题」分开定位。

5. 本篇常见报错排查

5.1 401 Unauthorized

最常见。先确认环境变量有没有生效：

echo $TAOTOKEN_API_KEY

如果为空，说明export没写进 shell 配置，或者当前终端没重新加载。再确认 settings.json 里apiKey字段拼写正确，没有多余空格。

5.2 404 Not Found

baseURL 写错了。正确是https://taotoken.net/api，不要多加/v1，OpenCode 内部会自己拼路径。如果你手动 curl 测试，才需要补/v1/chat/completions。

5.3 模型名不识别

defaultModel里的别名要和models映射里的 key 对上。比如你写taotoken/claude-sonnet，那models里必须有claude-sonnet这个 key。模型真实名称以 TaoToken 接入文档里的列表为准，别自己编。

5.4 模板不生效

opencode run refactor-module没反应，先检查.opencode/prompts/refactor-module.md是否存在，文件名是否和命令里的参数一致。再看 settings.json 的promptsDir路径是相对项目根目录还是绝对路径，两者别混。

5.5 权限报错

OpenCode 要读写仓库文件，如果目录权限不对会报错。确认当前用户对项目目录有写权限：

ls -ld your-project

必要时chmod调整，别用 root 跑，容易把文件属主搞乱。

5.6 网络超时

如果请求一直挂起，先确认能访问 TaoToken 的 API 入口：

curl -I https://taotoken.net/api

返回 200 或 401 都说明网络通，401 只是没带 Key。如果连不上，检查本地网络和 DNS，别急着改配置。

6. 按场景分流的下一步

搭到这里，OpenCode 的 CLI 已经能在终端里跑通首次对话，oh-my-opencode 的模板和规则也挂上了。接下来按你的实际场景走：

如果你卡在接入或排障上，重点看 API Keys 和接入文档，把 Key 管理和 baseURL 配置彻底搞明白：API Keys 入口在 https://taotoken.net/console/api-keys ，接入文档在 https://taotoken.net/doc 。

如果你想先验证模型效果、对比不同模型在同一个任务上的输出，直接去模型对话页面试：https://taotoken.net/chat 。

如果你打算长期用 OpenCode 做编码和 Agent 任务，比如每天跑 refactor、write-tests 这类模板，Coding Plan 更划算，入口在 https://taotoken.net/coding-plan 。

我自己的习惯是：新项目先用模型对话快速验证 Prompt 模板的措辞，确认输出稳定后再固化进.opencode/prompts/，最后用 Coding Plan 跑批量任务。这样模板质量有保证，Key 也不会在调试阶段被浪费。