OpenCode+Agent Skills实战：从零搭建终端AI Agent工作流

近段时间，终端 AI Agent 的热度明显上来了。Claude Code 把“让模型自己读代码、改文件、跑命令”变成了一件日常可做的事情，但并不是所有人都愿意被闭源生态和固定模型绑定住。于是开源替代成了更务实的选项，OpenCode 就是这类项目里关注度很高的一个。它经常被直接称为 Claude Code 的开源替代：同样在终端里工作，但代码开源、模型自由配置、支持技能扩展，还能用 CLI 方式跑批量任务。

这次我们不聊概念，直接把 Agent Skills 这条线完整打通：从零开始安装 OpenCode，接入一个第三方模型 API，再亲手写一个真正的 Skill，也就是带目录、带 SKILL.md、带输出模板的技能包，最后用非交互命令把它变成可批量执行的工作流。如果你之前只听过 Agent Skills 这个词，但不清楚它和 MCP 有什么区别、到底怎么落地，看完这篇应该能自己建一个技能并跑通。

本文面向的读者很简单：想用开源工具搭本地 Agent 工作流的人。不管你是写代码、做文档处理、还是做研究辅助，只要想让模型按固定流程干活，这篇都适用。先说结论：整个工具链的部署成本很低，CLI 本身几乎不占资源，真正的开销在模型 API 的 token 费用。下面按步骤拆解。

1. Agent Skills 与 OpenCode 核心能力速览

先给一张速览表，方便你快速判断这个组合适不适合自己。

选择 OpenCode 而不是直接使用 Claude Code 的几点实际理由：第一，开源，你可以审查它到底做了什么，也能在需要时修改和扩展；第二，模型不绑定，DeepSeek、OpenAI、Gemini、本地 Ollama 都可以接；第三，Skills 机制允许你把团队流程沉淀成技能文件，后续复用非常方便；第四，opencode run这种非交互模式，天生适合做自动化和批处理。当然它也不是没有缺点，整个项目还在快速迭代，文档和生态相对年轻，版本更新频繁，所以后面会专门讲配置兼容问题。

2. 适用场景与使用边界

从实际使用看，OpenCode 加 Agent Skills 的组合主要解决三类问题。

第一类是开发场景。代码审查、单元测试补充、重构建议、bug 修复都能交给 Agent。如果把代码审查规范写成 Skill，团队里任何人发起审查请求，Agent 都会按同一套标准输出报告，而不是每次凭模型心情自由发挥。

第二类是文档与知识处理。Markdown 批量整理、日志分析、周报生成、会议纪要结构化，这些任务属于典型的重流程、轻创造，非常适合做成 Skill。研究场景也有实际案例，比如有人在用 Agent Skills 辅助论文写作，把研究问题拆解、文献整理、行文润色这些流程沉淀成技能文件，用的时候直接调。

第三类是批处理与自动化。opencode run配上脚本，可以逐个处理目录下的任务文件，也可以接进 CI，在每次提交或者发版时自动触发一次 Agent 审查。

使用边界也要说清楚。这个工具不适合完全不看代码、不核对输出的人。Agent 会错，Silent 出错比人固执得多，关键修改必须人工复核。对数据安全要求极高、连代码和文本都不想出内网的团队，要么接本地模型，要么就不要用云端 API。另外凡是涉及版权素材、人脸、声音、隐私数据、学术成果的内容，都要先确认授权和合规要求，这个没有商量空间。论文写作场景下，AI 只能辅助整理格式和润色文字，观点、数据、引用来源必须本人负责，并且要遵守所在学校和期刊关于 AI 使用的规定。

3. 环境准备与前置条件

在开始安装之前，先把环境检查清楚，能省掉后面一大半排错时间。

3.1 操作系统与基础工具

OpenCode 是典型的终端工具，对操作系统要求不复杂。Windows 10/11、macOS、主流 Linux 发行版都能跑。Windows 用户如果遇到 PATH 或者脚本执行问题，优先考虑用 WSL 环境，会省事很多。

基础工具方面，如果准备用 npm 安装，需要 Node.js 环境，版本建议 18 以上，具体以项目官方文档要求为准。如果只是下载二进制，则不需要 Node。Git 是必须的，因为大部分 Agent 任务的载体是代码仓库，而且后续要执行的 git diff、git log 操作都依赖 Git。

终端工具也很关键。Windows 上推荐 Windows Terminal，macOS 直接用系统自带终端或者 iTerm2 都行。关键是你要能方便地复制粘贴、查看长输出，因为 Agent 的思考和执行日志有时候会很长。

3.2 模型 API 与网络前提

OpenCode 本身只是一个终端工具，真正干活的是背后的大模型。你需要提前准备一个能正常访问的模型 API。常见选择包括 DeepSeek、OpenAI、Anthropic、Google Gemini，也可以用本地模型服务，比如通过 Ollama 在本地跑开源模型。

选云端 API 的话，去对应平台创建一个 API Key，确认账户有可用额度。这一步不准备好，后面所有调用都会报 401 或者额度错误。注意保管好密钥，不要提交到 Git 仓库，不要写进公开配置文件。

如果使用本地模型，需要确认机器有足够的 CPU 和内存，GPU 则取决于你选的模型。这里不展开具体显存数字，因为不同模型差异太大，建议以模型发布页面给的硬件要求为准。

3.3 磁盘与目录规划

CLI 工具本身占用空间很小，真正需要规划的是工作目录。建议给 Agent 任务建独立目录，输入、输出、日志分开。比如项目根目录下建tasks/、outputs/、logs/三个目录，批量跑任务的时候，每个任务对应一个输入文件、一个输出文件、一个日志文件，排查问题会非常方便。

4. 安装部署与启动方式

安装方式有很多种，这里给一套完整可用的流程。命令都是通用模板，具体版本和路径以你安装时的官方文档为准。

4.1 官方安装脚本（macOS / Linux）

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

这是官方文档给出的脚本方式，执行完会自动安装到用户目录，并提示你添加 PATH。安装完成后，重新打开终端，或者执行source ~/.bashrc/source ~/.zshrc让 PATH 生效。

4.2 npm 全局安装

npm install -g opencode-ai opencode --version

如果本机已经有 Node.js 环境，这是最方便的方式。安装成功后，先跑一下--version验证。如果 Windows 下提示无法识别 opencode，通常就是 npm 全局目录不在 PATH 里，后面会在排查部分专门说。

4.3 Windows 安装

Windows 用户可以直接从 GitHub Releases 下载最新的 Windows 发行版二进制，放到一个已经加入 PATH 的目录里，比如C:\Users\你的用户名\bin，然后重新打开终端验证。也可以直接在 WSL 里按 Linux 方式安装，通常体验更顺。

4.4 离线安装思路

内网环境先把发行包下载后拷贝到目标机器，解压到固定目录，然后手动把该目录加入 PATH。npm 方式也可以在有网机器上先下载离线 tgz，再导入内网安装。注意版本要选对，Windows 和 Linux 的包不能混用。

4.5 启动与首次登录

opencode

首次启动会看到模型选择的引导界面。OpenCode 默认会从模型注册中心拉取供应商列表，你可以选择已经配置好密钥的供应商登录。启动后进入全屏 TUI 对话界面，下方是输入框，上方是对话记录和文件变更区域。这个界面基本不需要鼠标，键盘就能完成大部分操作。

4.6 验证安装

opencode run "请用一句话回答：什么是 Agent Skills？"

能正常输出一段合理的回答，就说明安装、密钥、网络三步都通了。这一步跑不通，后面所有功能都不用试，先解决环境问题。

5. 配置第三方模型 API 与切换模型

默认情况下，OpenCode 支持通过官方 auth 流程登录各家模型供应商。但实际使用中，很多人更习惯把 DeepSeek 这类第三方 API 接进来。下面给两种配置方式。

5.1 环境变量方式

export DEEPSEEK_API_KEY="sk-你的key" export OPENCODE_MODEL="deepseek/deepseek-chat" opencode

其中DEEPSEEK_API_KEY是 DeepSeek provider 常见的环境变量名，OPENCODE_MODEL用来自动选择模型。具体支持的变量名以当前版本为准。如果你不确定，先看启动日志，里面有模型注册信息。

5.2 使用 opencode.json 配置自定义 Provider

OpenCode 支持 OpenAI 兼容协议的自定义 provider。在项目根目录，或者全局配置目录，创建opencode.json：

{ "$schema": "https://opencode.ai/config.json", "provider": { "custom-deepseek": { "npm": "@ai-sdk/openai-compatible", "name": "Custom DeepSeek", "options": { "baseURL": "https://api.deepseek.com/v1", "apiKey": "{env:DEEPSEEK_API_KEY}" }, "models": { "deepseek-chat": { "name": "DeepSeek Chat" }, "deepseek-reasoner": { "name": "DeepSeek Reasoner" } } } } }

这段配置的字段结构是通用示例，不同版本可能有差异。核心思路是把baseURL指向第三方服务的 OpenAI 兼容端点，在models里声明你实际需要的模型。配置完成后，用opencode run验证一下能不能正常调用。如果 JSON 写错了，启动时会直接报配置解析错误。

5.3 模型切换与 model ID 问题

使用模型时，OpenCode 里的模型路径一般是provider/model的格式。配置文件里声明了custom-deepseek之后，调用时写custom-deepseek/deepseek-chat即可。命令行方式也可以指定模型：

opencode run --model deepseek/deepseek-chat "写一个 Go 语言的 hello world"

热词里经常出现的那条报错，'deepseek-v4-pro' is not a model this version of claude code recognizes，本质上就是模型 ID 不在当前程序的模型注册表里。用 OpenCode 排查时先看清两点：模型 ID 是否真实存在，当前版本是否支持。不要照搬别人截图里的模型名。遇到类似提示，先升级工具版本，再核对模型 ID 拼写。

6. Agent Skills 实战：创建第一个技能

配置好模型以后，直接进入正题：创建一个能被 Agent 自动调用的技能包。

6.1 Agent Skills 到底是什么

Agent Skills 不是一个大模型，而是一种给 Agent 用的“技能包”。每个 Skill 是一个目录，里面至少有一个SKILL.md。这个文件用 Markdown 写清楚技能在什么时候用、按什么步骤执行、输出什么格式。模型读到description后，会在用户请求命中时自动加载并遵守这个流程。

很多人会混淆 Skill 和 MCP。区分的方法很简单：MCP 是给 Agent 接外部工具和数据的，典型场景是让 Agent 查数据库、调用内部系统 API；Skill 是给 Agent 安装“内在流程”的，典型场景是让 Agent 按你们团队的代码审查规范、写作模板、数据处理流程来干活。两者可以配合使用，但不冲突。

6.2 技能目录结构

OpenCode 会在项目根目录读取.opencode/skills下的技能，也可以放到用户级全局配置目录作为跨项目技能。一个技能目录长这样：

project/ .opencode/ skills/ code-review/ SKILL.md checklist.md weekly-report/ SKILL.md template.md

每个子目录就是一个独立的技能。目录名建议用英文小写加短横线，便于 Agent 通过目录名和description双重匹配。如果目录放错位置，Agent 不会报错，但技能永远不会被触发，这是最隐蔽的坑。

6.3 写一个代码审查 Skill

我们直接写一个code-review技能，放到任意代码仓库都能用。先在.opencode/skills/code-review/下创建SKILL.md：

--- name: code-review description: 对当前分支相对主分支的改动进行代码审查。用户说“审查代码”“帮我 review 一下”“检查提交”时使用。 --- # 代码审查技能 ## 使用场景 - 用户要求审查当前分支的代码改动 - 提交 PR 之前做提交前检查 - 只审查某个文件或某次提交 ## 执行步骤 1. 运行 git diff --stat 查看改动文件列表。 2. 运行 git diff 查看具体改动内容。 3. 如果用户指定了文件或提交，则缩小范围到对应文件或提交。 4. 按 checklint.md 中的检查项逐项核对。 5. 输出一份报告，包含问题定位、严重级别 P0/P1/P2、修复建议。 ## 输出格式 - 大标题：Code Review 报告 - 按严重级别分组列出问题 - 每个问题包含文件路径、问题描述、建议修复方式 ## 注意事项 - 不要修改任何文件，只输出报告。 - 如果 diff 为空，直接说明没有需要审查的改动。

这里注意一个细节：description要写清楚触发条件和典型说法。Agent 是根据 description 判断要不要启用这个技能的，写得太模糊，它就不会触发。

同时可以在同目录放一个checklist.md，把团队关心的检查项写进去，比如错误处理是否完善、日志是否规范、敏感信息有没有硬编码、依赖版本是否锁定。Agent 执行时会读取这个文件作为检查依据。

6.4 触发测试

opencode run "review 当前分支的代码改动"

正常工作时，Agent 会读取 SKILL.md，然后按里面的流程执行 git 命令，最后输出一份结构化的审查报告。这里判断成功的标准不是“回答得漂不漂亮”，而是它是否真的执行了技能里规定的步骤。如果它直接凭经验回答，而没有跑 git diff，就说明技能没有被加载。

6.5 扩展：写作辅助技能

研究场景同样可以做技能包。比如创建一个paper-writing技能，把论文摘要的打磨规则、引用格式规范、段落衔接要求写进 SKILL.md。这类技能的价值在于，把之前每次都要重复交代的写作约定固定下来，团队或者个人后续直接调用。

学术场景要特别注意合规。AI 只能辅助整理格式、润色语言，不能替代研究者完成观点和数据的真实性判断。使用前确认所在单位对 AI 辅助写作的要求，并在成稿中按照学术规范说明 AI 参与情况。

7. 功能测试与效果验证

工具装完、技能写完，接下来按维度测一遍，不要一上来就跑大任务。

7.1 基础对话测试

测试目的是验证安装、密钥、网络三条链路是否通畅。运行：

opencode run "用一句话解释什么是回调函数"

能正常输出即可。如果这一步失败，优先检查 API Key 和网络。

7.2 工作区文件测试

测试目的是验证 Agent 是否具备读写文件能力。在空目录运行：

opencode run "在当前目录创建一个 notes.md，写入今天的日期，并总结本项目的目录结构"

正常结果是文件被创建，内容合理。如果 Agent 只输出内容但没有真的写入文件，说明当前环境的文件操作权限或者工具调用有问题。

7.3 多文件与长上下文测试

测试目的是观察 Agent 在较大代码库中的表现。运行：

opencode run "读取项目 README.md，列出项目的主要模块和入口文件，输出到 modules.md"

这一步会涉及多文件读取和写回，能比较真实地反映工具在项目级任务上的稳定性。上下文越长，token 消耗越大，这也是观察成本的好机会。

7.4 Skill 触发测试

使用前面创建的 code-review 技能，在一个有 git 改动的仓库里运行：

opencode run "审查代码改动"

判断依据是输出结果是否符合 SKILL.md 约定的格式，是否包含 diff 统计、问题列表、严重级别和修复建议。如果输出格式完全不对，回到技能目录检查文件位置和 frontmatter。

7.5 常见失败原因

这一套流程最容易翻车的点有三个：一是模型不支持工具调用，导致 Agent 读不到文件；二是技能目录放错位置；三是 prompt 里限制太多，Agent 为了迎合用户而选择性执行步骤。遇到输出异常，先看日志，再逐项排除。

8. 接口 API 与批量任务：opencode run 非交互模式

OpenCode 除了 TUI 交互模式，还提供了opencode run非交互模式，这是做批量和接口集成的关键。它的输出可以直接进文件、管道、日志系统。

8.1 非交互模式

普通交互模式适合人在终端里实时看过程。非交互模式适合脚本调用，例如：

opencode run "分析 out.log 中的错误信息，并给出修复建议"

这条命令执行完就会退出，stdout 输出结果。你可以在脚本里捕获 stdout，也可以重定向到文件。

8.2 Python 调用示例

你可以把opencode run当作一个命令行子进程来调用。下面给一个 Python 封装：

import subprocess def run_agent(task: str, model: str = "deepseek/deepseek-chat") -> str: result = subprocess.run( ["opencode", "run", "--model", model, task], capture_output=True, text=True, timeout=600 ) if result.returncode != 0: raise RuntimeError(result.stderr) return result.stdout output = run_agent("读取 README.md，列出项目中的主要模块") print(output)

需要说明的是，--model参数的写法依赖当前版本。如果提示不识别，就换成配置文件里写好的provider/model字符串。超时时间也不要设置太短，Agent 任务通常需要几十秒。

8.3 批量任务脚本

批量任务的核心是三个原则：日志输出、失败不中断、结果目录隔离。下面给一个 Bash 模板：

#!/usr/bin/env bash set -euo pipefail mkdir -p outputs logs for file in tasks/*.md; do name=$(basename "$file" .md) echo "开始处理: $name" opencode run "根据 tasks/$name.md 的要求完成任务，结果写入 outputs/$name.md" \ >> "logs/$name.log" 2>&1 || echo "任务失败: $name" done

这个脚本会遍历tasks/目录下的每个 Markdown 任务文件，逐个调用 Agent，日志写入logs/，结果写入outputs/。单条任务失败不会中断整个队列，适合批量执行。没有这套日志和隔离机制，跑到一半失败，你根本不知道哪条任务卡住了。

8.4 接入 CI/CD 的通用思路

在 GitHub Actions 里可以把opencode run当作一个 step 来跑。密钥用 GitHub Secrets 注入环境变量，不要把 API Key 写进仓库。

- name: Run OpenCode Task env: DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }} run: | opencode run "审查本次 PR 的代码改动并输出审查报告"

这里只是一个通用模板，实际接入时，需要改成你项目里的触发条件和任务内容。CI 场景下建议给任务加超时限制，防止一次失误的任务烧掉大量 token。

8.5 接口化注意事项

如果你需要把 Agent 能力做成本地服务接口，最简单的方式不是在 OpenCode 里启动 HTTP Server，而是在你自己的业务脚本里用 subprocess 调用。这样隔离性更好，进程级别的崩溃不会影响主服务。如果要做对外 HTTP 接口，必须在前面加队列、限流和鉴权，否则任何人都能拿你的 API 额度跑任务。

9. 资源占用与性能观察

OpenCode 作为终端 CLI，自身资源占用很低，不需要担心显存问题