OpenCode Agent Masterclass：从安装到掌握的完整教程

本文为中文改写与评论，原文作者 Parvez Mohammed @ Techlatest.net，发布于 Medium；原文链接：OpenCode Agent Masterclass — Full Tutorial。本文保留原文的核心结构、命令和图片位置，并面向中文读者重新组织为一篇可操作的 OpenCode 入门到进阶指南。

OpenCode 的重点不只是“又一个代码聊天工具”，而是一个开源、provider-agnostic、终端优先的 coding agent harness：模型负责写代码，harness 负责工具、权限、上下文和完成标准。

这篇教程的目标很直接：让读者从零开始安装、配置并掌握 OpenCode。OpenCode 是一个开源 AI coding agent，官方定位覆盖终端 TUI、桌面应用和 IDE 扩展。原文强调它拥有 17.9 万以上 GitHub stars，支持多 provider、多模型路由、MCP、skills、LSP 和多会话工作流。

如果用一句话概括：OpenCode 不是把聊天窗口套在代码库外面，而是把模型放进一个工程化 harness 里，让它能读文件、改代码、跑命令、理解项目规则，并在权限边界内推进任务。

读完你应该得到什么

• 知道如何用 curl、npm 或 Homebrew 安装 OpenCode。
• 理解如何通过 /connect 连接 OpenCode Zen、Anthropic、OpenAI、Ollama、Copilot 等 provider。
• 知道 /init 如何为项目生成 AGENTS.md，并为什么应该把它提交到 git。
• 掌握 Build 与 Plan 两种 agent 模式，以及用 Tab 切换的工作方式。
• 理解 MCP、rules、permissions、skills、undo、redo、share 和 @ 文件引用的日常用法。

OpenCode 的定位：在你工作的地方陪你写代码

OpenCode 不是另一个简单的 chat wrapper。它更像一个面向软件工程的 agent harness：支持文件编辑、shell 执行、LSP 代码智能、MCP 工具服务器、subagents、多会话并行，以及终端、桌面应用和 VS Code 扩展等多个入口。

它的产品主张也很清楚：privacy-first、provider-agnostic、MIT 开源。你可以接 OpenCode Zen，也可以带自己的 Anthropic、OpenAI、Google、Groq、Ollama 或其他模型 provider。对于本地模型和 BYOK 场景，OpenCode 不把代码和上下文存到自己的服务器。

OpenCode 的结构

原文把 OpenCode 拆成几层来看：

1. Surfaces：终端 TUI、桌面应用、IDE extension、web。
2. Agents：build 负责实际修改，plan 负责只读分析。
3. Tools：文件操作、搜索、bash、web、代码智能、subagent spawn。
4. Configuration：rules、permissions、policies、formatters、keybinds。
5. Extensions：MCP servers、Agent Skills、自定义工具、LSP servers。
6. Model routing：通过 API key 或 OAuth 使用不同 provider，包括 Copilot 和 ChatGPT Plus/Pro 登录。

这里最重要的边界是：harness 决定模型什么时候能写文件、能看见哪些工具、会话如何保存；模型则在这个边界内进行推理和代码生成。

安装前提

原文建议使用 WezTerm、Alacritty、Ghostty 或 Kitty 这类现代终端。系统方面，macOS、Linux、WSL 都可以；Windows 也可以用 Scoop 或 Chocolatey，但很多开发者仍然会优先选择 WSL。

你还需要准备一个模型 provider：可以是 OpenCode Zen 订阅，可以是 Anthropic/OpenAI 等云端 API key，也可以是本地 Ollama。如果你要在某个代码库里使用 OpenCode，最好先保证这是一个 git repo，因为 /init 会生成项目级的 AGENTS.md。

node -v          # 如果选择 npm 安装路径，可以先检查 Node
which opencode  # 安装后确认命令是否可用

安装 OpenCode

最推荐的方式是官方一行命令：

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

安装目录优先级大致是 $OPENCODE_INSTALL_DIR、$XDG_BIN_DIR、$HOME/bin、$HOME/.opencode/bin。

也可以用常见包管理器：

npm install -g opencode-ai          # 也可以用 bun / pnpm / yarn
brew install anomalyco/tap/opencode # macOS/Linux，tap 通常更新较快

如果你更喜欢图形界面，可以从 opencode.ai/download 下载桌面 app，目前覆盖 macOS、Windows、Linux 的常见包格式。

配置模型 Provider

进入你的项目目录，启动 OpenCode：

cd /path/to/your/project
opencode

在 TUI 里输入：

/connect

对初学者来说，OpenCode Zen 是最省心的选择，因为它把适合 coding agent 的模型选择做了整理。更有经验的用户可以连接 Anthropic、OpenAI、Google、Groq、Ollama，或者用 GitHub Copilot、ChatGPT Plus/Pro 的 OAuth 登录。

如果你希望离线或半离线运行，原文也提到可以把 OpenCode 接到 Ollama-compatible endpoint。TechLatest 还推广了自己的 GPU-ready DeepSeek/Llama 环境、LocalAI、Chroma、RAGFlow 等服务。这里对中文读者的关键点是：OpenCode 的核心优势在于 provider neutral，你不用被单一模型厂商锁死。

用 /init 生成 AGENTS.md

连接 provider 后，可以在项目里执行：

/init

OpenCode 会分析仓库，并在项目根目录写入 AGENTS.md。这个文件通常描述项目结构、常用命令、测试方式、代码风格和 agent 工作时应该遵守的约定。

这其实就是 harness engineering 的基础动作：把项目背景和操作约束沉淀成一个可版本化的地图，而不是每次对话都重新解释。

# AGENTS.md 示例结构

## Project overview
Brief description of what this repository does and its primary language/framework.

## Directory layout
- src/   — application source
- tests/ — pytest or your runner
- docs/  — deep architecture notes

## Commands
npm install
npm test
npm run lint

## Conventions
- Prefer small PR-sized changes
- Run tests before claiming done
- Do not edit vendor/ or lockfiles unless asked

## Agent notes
- Read docs/architecture.md before large refactors
- Use Plan mode for unfamiliar modules

Build 与 Plan 两种 Agent 模式

OpenCode 提供两个核心 agent：Build 和 Plan。Build 可以真正修改文件、执行命令；Plan 更偏只读分析，用来理解代码、拆解任务、形成方案。原文建议使用 Tab 在两者之间切换。

一个推荐工作流是：

1. 先切到 Plan。
2. 把需求描述清楚，像给一位初级工程师交代任务一样提供上下文和约束。
3. 和 agent 迭代计划。
4. 确认后切到 Build。
5. 让它按计划实现，并检查 diff、测试和结果。

这种模式的价值在于把“理解问题”和“修改代码”分开。尤其是陌生代码库、复杂重构或高风险修改，先 plan 再 build 往往能减少无谓返工。

Tools 层：Agent 的手

OpenCode 的工具层包括文件读写、搜索、bash、web、LSP 代码智能以及 subagents。模型不是直接“魔法般”改变代码，而是在 harness 暴露的工具边界内发起操作。

这也是 agent 系统真正走向工程化的关键：工具能做什么、什么时候需要权限、观察结果如何回到模型上下文，都应该由 harness 管理，而不是完全交给一次 prompt。

Rules、Permissions 与 Policies

Rules 是项目级或组织级说明，影响 agent 的行为方式。Permissions 是工具调用的 allow/deny 策略，尤其是 Plan 模式通常会更严格。Policies 则适合团队或企业场景，约束更高层级的安全边界。

## Project rules (OpenCode)

Never commit secrets or .env files
Run npm test && npm run lint before finishing a task
Ask before deleting files or running destructive shell commands
Match existing code style in each directory

中文读者可以把它理解成“把踩过的坑写成持久约束”。比如不许提交 secrets、删除文件前必须确认、完成前必须跑测试，这些都不应该只靠模型临场发挥。

MCP Servers

OpenCode 支持 MCP，也就是 Model Context Protocol。MCP 的作用是让 agent 能通过统一协议调用外部工具，比如数据库、浏览器、Stripe、文件系统、内部服务等。

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed"]
    }
  }
}

MCP 和内置工具的关系可以这样理解：内置工具让 OpenCode 直接拥有代码编辑和搜索能力；MCP 则把外部系统接进 agent loop，让它能在更大的工作环境中行动。

Agent Skills

Agent Skills 是一组打包能力：可以包含说明、脚本、参考资料和资源。它的核心思想是 progressive disclosure，也就是不要一开始把所有东西都塞进上下文，而是在任务相关时再加载对应 skill 的完整说明。

从系统设计角度看，MCP 和 Skills 是互补的：MCP 更像工具调用协议，Skills 更像可复用工作流和操作手册。一个负责“能调用什么”，一个负责“该怎么做”。

日常使用模式

探索代码库时，可以用 @ 引用文件：

How is authentication handled in @packages/functions/src/api/index.ts

添加功能时，推荐先 Plan 后 Build。直接改小功能时，也可以明确告诉 agent 对照某个已有文件的模式：

We need auth on /settings. Mirror the pattern in @packages/functions/src/notes.ts
and apply it in @packages/functions/src/settings.ts

如果任务涉及 UI，OpenCode 也支持把 PNG/JPG 拖进 TUI，让图片成为 prompt 的一部分。

Undo、Redo 与 Share

OpenCode 也提供了几个非常实用的会话命令：

/undo
/redo
/share

/undo 可以撤回一次不满意的修改，并把你的原始消息带回来，方便调整提示后重新执行。/redo 用于恢复。/share 会创建当前会话的分享链接，方便团队调试 agent 行为。

多会话与 LSP

OpenCode 支持在同一个项目中运行多个并行 agent session。对前后端分工、多个独立 bug、文档和代码并行推进这类场景很有用。

LSP 集成则让 harness 能把更语义化的代码信息喂给模型，比如符号、诊断和补全上下文。相比纯粹复制粘贴代码给聊天窗口，这是一层很实际的工程优势。

终端之外的 Surfaces

原文强调，同一个 harness 可以跑在不同 surface 背后：终端、桌面、IDE 或 web。这样用户入口可以不同，但模型看到的工具层和工作规则是一致的。

SDK、Server 与 Plugins

对于想扩展 OpenCode 的开发者，原文提到三类能力：

• SDK：以编程方式访问 agent harness。
• Server：把 OpenCode 当作服务运行，让其他客户端接入。
• Plugins：不 fork 核心代码也能扩展行为。

如果你发布衍生项目，OpenCode 上游也希望在 README 中明确说明该项目不是官方项目。

OpenCode 在 Agent 工具体系中的位置

和 Claude Code 相比，OpenCode 更强调开源透明、provider-neutral 和终端优先；Claude Code 则是 Anthropic-native，并且在 Claude 生态和 IDE 集成中很强。

和 OpenClaw 相比，OpenClaw 更像个人助手网关，适合 Telegram、WhatsApp、cron 等生活和自动化场景；OpenCode 则是 repo coding agent，面向软件工程仓库。两者可以互补，而不是一定互相替代。

原文还把 OpenCode 和 ZeroClaw 做了对比：ZeroClaw 更像 Rust 多通道 runtime，强调安全策略和硬件 hooks；OpenCode 则优化 developer UX 和 git repo 内的编码流程。

Troubleshooting 与检查清单

原文最后给出一组非常短的上手检查清单：

curl -fsSL https://opencode.ai/install | bash
cd your-repo && opencode
/connect
/init && git add AGENTS.md && git commit -m "Add OpenCode AGENTS.md"
# Tab -> Plan -> describe feature -> Tab -> Build -> implement
/share    # optional: link for teammate

给中文读者的总结

OpenCode 值得关注的地方，不只是它“能写代码”，而是它把 coding agent 所需的工程结构放到了前台：AGENTS.md、Plan/Build 模式、permissions、MCP、skills、LSP、多会话和可撤销修改。

如果你只是偶尔问 AI 几个代码问题，普通聊天窗口就够了。但如果你希望 agent 真正在代码库里长期工作，OpenCode 这类 harness 的价值会越来越明显：它把上下文、权限和操作流程固化下来，让每次工作都不是从零开始。

更大的趋势是：未来的 coding agent 竞争，不会只看“模型回答得多聪明”，还会看 harness 是否能把模型稳定接入真实工程环境。OpenCode 给出的答案是开源、终端优先、provider-neutral，并且把项目地图、工具层和权限边界都做成一等公民。

资料来源

• Medium 原文：Parvez Mohammed @ Techlatest.net, “OpenCode Agent Masterclass — Full Tutorial”
• OpenCode 官网：opencode.ai
• OpenCode 文档：opencode.ai/docs
• OpenCode GitHub：github.com/anomalyco/opencode