很多朋友在上篇里已经跑通了 opencode 的基础流程但一接触真实项目就发现光会/chat不够工具链怎么组织、模型服务层怎么配、怎么把 opencode 嵌入编辑器甚至 Git 流程才是真正决定体验上限的地方。这篇下篇我直接拆工具、服务面、外壳和实战集成四块把我在几个中型项目里反复试出来的配置和踩坑记录都摊开讲希望能给你一条相对顺的路线。1. 工具面CLI、TUI 与配置管理opencode 不只是一个“终端聊天框”它本质上是把 CLI、TUI、配置文件和本地权限模型组装成一套可编程的编码代理工具箱。想用好它先从这几个基础件说起。1.1 命令行参数与交互界面opencode 的默认行为是启动一个全屏 TUI但真实项目里你往往需要非交互调用比如在脚本里跑一次代码审查、在 CI 里生成 commit message。这就需要区分几类命令场景# 进入交互式 TUI opencode # 以单次请求方式运行适合脚本或管道 opencode run 审查 src/ 下最近的改动 # 指定模型 opencode --model deepseek/deepseek-chat # 继续上一个会话 opencode --continue # 列出历史会话并选择继续 opencode --sessionrun子命令是我最常用的。它接受自然语言指令opencode 会按配置好的 Agent 模式去读文件、执行命令、产出结果。配合--session参数可以指定一个已有会话 ID这样能把多步任务拆成多个run调用但上下文又不会丢。TUI 本身的快捷键也很关键尤其是和编辑器联动时操作快捷键说明切换输入模式i进入/退出正常编辑输入提交消息Enter发送当前输入中断生成Esc停止当前响应切换 Agent/Plan 模式Tab在自动执行与只读规划之间切换查看差异d展示待应用的代码 diff初次使用时我建议把Tab切换到 Plan 模式让 opencode 先给出修改计划确认后再切回 Agent 模式执行。直接让 Agent 动文件出问题排查成本高。1.2 配置文件分层与 Provider 注册opencode 的配置遵循“全局 项目”两层覆盖逻辑。全局配置放用户目录项目配置放仓库根目录字段合并项目配置优先。一个典型的~/.config/opencode/opencode.json长这样{ $schema: https://opencode.ai/config.json, model: anthropic/claude-sonnet-4-5, provider: { anthropic: { options: { apiKey: {env:ANTHROPIC_API_KEY} }, models: { claude-sonnet-4-5: { name: Claude Sonnet 4.5 } } }, deepseek: { options: { apiKey: {env:DEEPSEEK_API_KEY} } } } }这里有个细节{env:ANTHROPIC_API_KEY}这种写法是在运行时读取环境变量而不是把密钥明文写进文件。我见过有人直接把 key 写进配置后把仓库推到远端第二天就收到账单警告这种事一定要避免。项目内的.gitignore记得把.env排除再用类似 dotenv 的方式加载。Provider 是 opencode 抽象出来的“模型服务面”。一个 Provider 可以包含多个 model每个 model 还可以单独指定tools开关、contextWindow、maxOutputTokens等参数。如果你用的是企业内部的 OpenAI 兼容网关也可以把所有模型统一挂到同一个 Provider 下用options.baseURL指到网关地址。1.3 免费额度限制与常见报错很多朋友第一次跑 opencode 用的是内置的免费模型入口然后遇到这样的报错Error from provider (console): opencodes free tier can only be used from within opencode这个提示的准确含义是该免费额度只在官方客户端环境中可用。你用自定义 Provider 或第三方网关去调用同一个模型标识时服务端识别不到官方客户端上下文就会拒绝。解决思路不是去“变造请求头”绕过而是走正规路径如果你确实想用某个模型的免费额度就通过官方支持的客户端入口使用比如 opencode 初始化时默认生成的 console provider。如果需要在团队内共享模型服务自己申请一个 API Key或者在内部网关上配置好计费与鉴权把baseURL指向合规网关。不要随便把provider改成不明来源的聚合网关安全性和稳定性无法保障还容易泄露代码片段。我把这个错误和另外几个高频报错放在一起方便对照排查报错信息常见原因处理方式free tier can only be used from within opencode非官方客户端调用免费模型改用官方 console provider 或自备 API Keymodel not found模型名写错或 Provider 未注册核对 provider 配置的 models 列表ECONNREFUSED本地 MCP 服务未启动检查副进程是否在监听对应端口permission denied权限规则拦截了文件写入在 permission 配置中显式 allow 路径或命令如果你是在 Ubuntu 服务器上用的注意 opencode 的日志位置一般收敛在~/.local/share/opencode/log排查问题时先去看日志尾部比在 TUI 里瞎按高效得多。2. 服务面Agent、Skill 与 MCP 生态“服务面”是我自己习惯的说法指的是 opencode 运行时依赖的各种能力提供者模型推理服务、技能定义、以及通过 MCP 协议接入的外部工具。这三块合起来才让 opencode 从“聊天机器人”变成“能动手改代码的执行器”。2.1 会话机制与 Agent 模式opencode 的每个会话都维护独立的上下文窗口上下文里会自动注入当前目录结构、打开文件摘要、最近 Git 状态以及你定义的技能说明。这也是它比单纯 API 调用更“懂项目”的原因。Agent 模式是核心你下一条指令后opencode 会自己决定调用哪些内置工具比如读取文件、执行 shell 命令、写代码然后根据输出决定下一步。整个过程像一位实习生在你机器上干活但它每一步命令都需要经过本地权限策略确认这是我很看重的安全设计。权限策略可以通过配置文件声明{ permission: { allow: [ bash: git status, read: src/**, edit: src/** ], deny: [ bash: rm -rf *, edit: .env* ], ask: bash: * } }三条规则的含义分别是无条件允许读取源码和执行特定 git 命令无条件拒绝删除操作和修改密钥文件其余 bash 命令每次弹确认。实际运行中如果同一个命令规则出现在allow和deny以deny为准。Plan 模式则完全只读它只用来生成方案、阅读代码、分析调用链。我在重构旧模块时一定会先用 Plan 模式拿到改动点清单再切回 Agent 模式执行。原因是 Agent 模式在上下文不够清晰时容易“多做”比如顺手格式化了你不想动的文件。2.2 Skill 技能系统的搭建与自定义Skill 是 opencode 里“可插拔能力包”的实现方式。一个 Skill 本质上是带元数据的 Markdown 文档加可选的脚本资源放在特定目录后opencode 就能识别并注入到上下文中。下面是一个规范的最小 Skill 目录.opencode/ skills/ changelog/ SKILL.md scripts/ generate.shSKILL.md的内容可以非常结构化--- name: changelog description: 根据 commit 历史生成 CHANGELOG.md args: scope: string --- 当用户要求生成 changelog 时执行以下步骤 1. 读取最近 30 条 commit 的 subject 和 body。 2. 按 conventional commits 分类feat、fix、docs、chore。 3. 调用 scripts/generate.sh 输出完整 CHANGELOG.md。Skill 的优势在于它会把“行为协议”而不是“一次性 prompt”固化下来。你在任何会话里只需要说“用 changelog 技能生成这周的变更记录”opencode 就会按 SKILL.md 里的指示执行而不是每次重新理解你的偏好。自己写 Skill 时我总结出三个要点description要写得很明确因为模型是靠它决定何时调用技能。步骤尽量拆细每一步给出可验证的输出比如“生成后运行git diff --stat”。不要在 Skill 里要求模型访问网络下载依赖这很容易触发权限阻断。搭建 Skill 时注意目录名不要带空格且name字段必须与目录名一致不然 opencode 的索引会找错。2.3 MCP 工具接入与安全边界MCPModel Context Protocol让 opencode 可以连接外部数据源和工具服务比如 GitHub、数据库、浏览器、企业内部 Wiki。配置通常写在opencode.json的mcp字段{ mcp: { github: { command: npx, args: [-y, modelcontextprotocol/server-github], env: { GITHUB_TOKEN: {env:GITHUB_PERSONAL_TOKEN} } }, playwright: { command: npx, args: [-y, playwright/mcplatest] } } }MCP 服务分为 stdio 和 HTTP 两类。上面例子是 stdio由 opencode 作为子进程拉起适合本机服务如果是远程服务就用url字段指向 HTTP endpoint。我对 MCP 的建议永远是“最小权限”。别一股脑把所有服务全接进来每多一个工具模型在决策时多一层选择噪音出错的概率也更高。比如接 GitHub MCP 时token 只开repo读权限等到确实需要创建 PR 时再追加写权限。另外env里引用的密钥同样要使用{env:...}形式不要把实际 token 写进代码仓库。3. 外壳编辑器、终端与自动化适配外壳层决定 opencode 怎么跟你的日常开发环境共生。我见过两种极端一种只在独立终端里用 opencode切文件要用编辑器另一种完全不碰编辑器全靠 Agent 改代码。合理的做法是让 opencode“长”在你的编辑器旁边各管一摊。3.1 在 VS Code 中与 opencode 协同opencode 与 VS Code 的协作有很多种姿势没必要强制二选一。首先是最简单也最稳定的方式在 VS Code 集成终端里启动 opencode。你可以通过快捷键Ctrl调出终端然后运行 opencodeTUI 会占用当前终端面板但旁边的代码文件仍然可以随时跳转查看。配合 VS Code 的workbench.action.terminal.split把终端拆成上下两个上面跑 opencode下面跑测试命令效率很高。如果想更“GUI”一些可以装社区提供的 OpenCode 扩展。扩展的运行模式是在侧边栏打开聊天面板后台调用 CLI 进程完成 Agent 执行。不过我对这个方案持保留态度因为扩展的更新速度往往落后于 CLI 核心偶发连接不上后端的情况。我的建议是本地开发用集成终端 TUI轻量查看用扩展生产脚本一律用opencode run。VS Code 里还可以给 opencode 配一个快捷键免去每次手敲命令[ { key: ctrlalto, command: workbench.action.terminal.sendSequence, args: { text: opencode --continue\r } } ]这样我在处理一个需求时随时按一下快捷键就回到上一次会话上下文连续不用重新解释背景。3.2 终端别名、历史会话与 Git Hooks终端的日常手感很大程度上来自别名和流水线。我常用下面几个alias ocopencode alias ocpopencode --plan alias occopencode --continue alias oclsopencode --session继续会话时ocls会输出一个列表里面包含会话 ID 和最后一条消息摘要。配合 fzf 可以做快速选择occ() { local sid sid$(opencode --session 2/dev/null | fzf | awk {print $1}) if [[ -n $sid ]]; then opencode --session $sid fi }把这类函数写进~/.zshrc或~/.bashrc日常使用会顺手很多。Git Hooks 是另一个值得投入的地方。比如在pre-commit阶段让 opencode 做一个轻量的 lint 修复#!/usr/bin/env bash # .git/hooks/pre-commit STAGED_FILES$(git diff --cached --name-only --diff-filterACM | grep -E \.(ts|js|py)$) if [ -n $STAGED_FILES ]; then opencode run 修复 $STAGED_FILES 中的 lint 问题并且不要改变业务逻辑 fi注意不要在 pre-commit 里跑完整的代码生成任务那会让提交变得很慢。它更适合做快速修补真正基于上下文的改动建议放到交互会话里做。还有一点如果 Hook 里运行 opencode涉及权限确认时会卡住 Git 流程所以这类 Hook 建议给 opencode--yes参数并配置好权限白名单。3.3 多模型选型与服务面取舍“opencode 和 DeepSeek Hermes 哪个好”这类问题没有标准答案因为要看模型服务面怎么配置。opencode 的强大之处在于它不绑定某一家模型你可以按任务类型切换。我在实践中的选择标准有四个上下文长度、工具调用稳定性、响应速度、单次成本。比如处理大型仓库全局搜索时上下文长度优先处理需要反复修改同一文件的任务时工具调用稳定性优先平时写脚本、写文案速度优先。模型示意上下文工具调用适合场景Claude Sonnet 4.5很长稳定大仓库重构、复杂多步任务DeepSeek Chat中等良好日常增删改、测试生成Hermes 4社区免费中等一般快速原型、解释代码切换模型不需要重启 opencode在 TUI 里输入/models即可列表选择也可以直接用opencode --model deepseek/deepseek-chat启动。我的建议是至少配一个强模型和一个快速便宜的模型强模型用来做架构分析和复杂任务快模型用来做重复劳动。这样既能保证质量也能控制成本。免费模型做日常小任务完全够用但对关键代码改动还是要用高质量模型审查一遍。4. 实战集成从安装到完整工作流这一章节我把从零到一的过程完整拉一遍安装、配置、建技能、执行任务、排查问题。你有项目在手边的话可以照着走一遍感受会更直观。4.1 Ubuntu 环境安装与升级Ubuntu 下安装 opencode 有这么几种方式# 方式一官方安装脚本推荐 curl -fsSL https://opencode.ai/install | bash # 方式二npm 全局安装 npm install -g opencode-ai # 方式三下载二进制后手动放入 PATH # 将解压后的 opencode 放到 ~/.local/bin安装完成后确认版本和路径opencode --version which opencode我在 Ubuntu 上遇到过的坑主要有三个PATH 没包含~/.local/bin脚本默认把二进制装到用户目录但 shell 找不到。在~/.bashrc里加入export PATH$HOME/.local/bin:$PATH。Node 版本过低如果选择 npm 安装建议 Node 18否则依赖安装时报错。升级后配置不兼容opencode 的配置 schema 会不断新增字段升级后最好跑一次opencode --doctor检查配置和 Provider 状态。升完级如果 TUI 启动异常多半是缓存问题。清掉~/.cache/opencode再重启即可不影响会话记录。4.2 实战为项目搭建 changelog 技能下面我以“自动生成 changelog”为例子完整演示 Skill 的搭建过程。首先在项目根目录建目录和文件mkdir -p .opencode/skills/changelog/scripts然后写SKILL.md--- name: changelog description: 基于 git 历史生成或追加 CHANGELOG.md args: scope: string days: number --- 生成 CHANGELOG.md 的规则 - 从 git log 中提取最近 {days} 天的提交。 - 按 feat / fix / docs / chore / refactor 分组。 - 每组下用项目符号列出 commit subject。 - 如果 CHANGELOG.md 存在则插入到 “# Changelog” 标题下方。 - 完成后运行 git diff --stat CHANGELOG.md 展示改动规模。接着写scripts/generate.sh#!/usr/bin/env bash set -euo pipefail SCOPE${1:-.} DAYS${2:-30} { echo # Changelog echo git -C $SCOPE log --since$DAYS days ago --prettyformat:%s|%h } /tmp/changelog_git.txt echo done脚本本身不用写太复杂opencode 会读取 SKILL.md 作为执行指引脚本只是给模型提供一个可复用的工具。调用时只需要在对话里说“用 changelog 技能生成最近 7 天的 changelog”opencode 就会自动拆分步骤。我特意把“验证输出”写进 SKILL.md因为 Agent 很容易在生成后什么都不检查就结束。加一步 diff 展示能显著降低“模型自嗨”的风险。4.3 端到端提交一个小需求假设现在要在项目中加一个新接口/api/v1/health并同步补测试。我实际的操作流程是这样在 TUI 输入/plan然后写“为项目新增一个 GET /health 接口返回 JSON 状态信息并补一个单元测试。”opencode 进入 Plan 模式后读取路由文件、控制器文件、测试文件输出一份改动清单包括新增文件路径和需要修改的已有文件。我在清单里看到它打算修改的一个配置文件中包含敏感字段于是在对话中追加一条“不要动配置文件只改路由和控制器测试文件放在 tests/health_test.ts。”切换/agent确认执行。opencode 会先创建文件然后运行测试命令并报告结果。这个过程中权限确认会出现两三次尤其是它尝试运行测试命令和写入新文件时。如果希望少点击确认可以预先在配置里allow对应路径和命令但我不建议一次性全量放行。全程大概几分钟比手动改完再写测试快不少关键是它对项目已有风格的模仿比较到位省去改格式的时间。4.4 高频问题速查与心得把这段时间遇到的高频问题整理成速查表方便你直接对照现象排查思路启动后模型列表为空检查opencode --doctor确认 Provider 配置和 API key 环境变量Agent 修改了不该改的文件使用 permission deny 规则提前封禁目录比如deny: edit: docs/**上下文太大导致报错减少会话延续次数或者用/compact压缩历史Skill 没有被识别检查目录名和name是否一致重启会话git hook 内 opencode 不输结果给 opencode run 添加--yes确保权限可自动放行TUI 中文显示乱码确认终端 locale 为UTF-8执行export LANGen_US.UTF-8我个人的体会是opencode 的上限不取决于它内置了多少能力而取决于你为它定义了多少边界。配置好权限白名单、写好可复用的 Skill、把模型服务面按任务分级它才能真正变成一个不添乱的团队成员。下一篇我打算专门写怎么把自定义 Skill 扩展到团队级共享让每个成员都能用同一套行为规范驱动 Agent这是我在多人协作项目里最受益的一点。