近段时间终端 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 核心能力速览先给一张速览表方便你快速判断这个组合适不适合自己。维度说明项目定位开源终端 AI Agent常被称为 Claude Code 的开源替代核心功能交互式对话、代码读写、执行命令、多文件处理、Skills 技能、MCP 工具接入模型接入内置多供应商模型注册支持 OpenAI 兼容协议的自定义 API 配置技能机制支持 SKILL.md 技能目录机制与 Claude Code 的 Agent Skills 一致启动方式终端命令启动交互模式opencode非交互模式opencode run支持平台Windows / macOS / LinuxWindows 可用二进制或 WSL 环境接口能力提供 CLI 非交互模式可写入脚本和 CI 流程批量任务通过opencode run循环或任务队列批量执行显存要求CLI 工具本身无显存要求若接本地模型则取决于模型自身要求适合场景代码审查与修改、文档处理、批量文本任务、研究辅助、私有化模型工作流选择 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 TerminalmacOS 直接用系统自带终端或者 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 / Linuxcurl -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_KEYsk-你的key export OPENCODE_MODELdeepseek/deepseek-chat opencode其中DEEPSEEK_API_KEY是 DeepSeek provider 常见的环境变量名OPENCODE_MODEL用来自动选择模型。具体支持的变量名以当前版本为准。如果你不确定先看启动日志里面有模型注册信息。5.2 使用 opencode.json 配置自定义 ProviderOpenCode 支持 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 查数据库、调用内部系统 APISkill 是给 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_outputTrue, textTrue, timeout600 ) 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 21 || 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自身资源占用很低不需要担心显存问题
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 核心能力速览先给一张速览表方便你快速判断这个组合适不适合自己。维度说明项目定位开源终端 AI Agent常被称为 Claude Code 的开源替代核心功能交互式对话、代码读写、执行命令、多文件处理、Skills 技能、MCP 工具接入模型接入内置多供应商模型注册支持 OpenAI 兼容协议的自定义 API 配置技能机制支持 SKILL.md 技能目录机制与 Claude Code 的 Agent Skills 一致启动方式终端命令启动交互模式opencode非交互模式opencode run支持平台Windows / macOS / LinuxWindows 可用二进制或 WSL 环境接口能力提供 CLI 非交互模式可写入脚本和 CI 流程批量任务通过opencode run循环或任务队列批量执行显存要求CLI 工具本身无显存要求若接本地模型则取决于模型自身要求适合场景代码审查与修改、文档处理、批量文本任务、研究辅助、私有化模型工作流选择 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 TerminalmacOS 直接用系统自带终端或者 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 / Linuxcurl -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_KEYsk-你的key export OPENCODE_MODELdeepseek/deepseek-chat opencode其中DEEPSEEK_API_KEY是 DeepSeek provider 常见的环境变量名OPENCODE_MODEL用来自动选择模型。具体支持的变量名以当前版本为准。如果你不确定先看启动日志里面有模型注册信息。5.2 使用 opencode.json 配置自定义 ProviderOpenCode 支持 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 查数据库、调用内部系统 APISkill 是给 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_outputTrue, textTrue, timeout600 ) 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 21 || 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自身资源占用很低不需要担心显存问题
