第一章：OpenCode 项目概览与核心定位
OpenCode 是一个开源的 AI 编码代理（AI coding agent）。它不是某个 IDE 的插件式补全工具，而是一个以终端为核心、可以读代码、改代码、跑命令、调用工具、自主完成多步开发任务的智能体。它的官方仓库位于 anomalyco/opencode，官网为 opencode.ai。
本教程基于 OpenCode 当前公开仓库与官方文档整理，面向中文读者系统讲解它的定位、安装、界面、配置体系、模型接入、Agent 自定义、命令与规则、工具与权限、MCP 扩展，并把重点放在自定义配置与「最省 Token、最高效」的最优化配置上。OpenCode 迭代非常快，本文出现的命令、字段与模型名称请以你当前版本的 opencode --help、/help、以及 opencode.ai/config.json JSON Schema 为准。
1.1 一句话理解
OpenCode 可以理解为：一个模型无关（model-agnostic）、终端优先、可深度自定义的开源 AI 编码智能体。
它通过 AI SDK 和 Models.dev 支持 75+ 个 LLM 提供商，可以同时使用云端模型（Claude、GPT、Gemini 等）和本地模型（Ollama、LM Studio、llama.cpp 等）。你可以在终端里和它对话，让它分析仓库、实现功能、修复 Bug、写测试、跑命令，并通过 Git 快照随时撤销它做的改动。
1.2 它解决什么问题
传统 AI 辅助编程常见的痛点是：
- 被某个厂商或某个模型锁定：换模型要换工具，配置无法复用。
- 黑盒、不可控：不知道它会执行什么命令、改哪些文件，缺少权限边界。
- 上下文与成本不可控：长会话不断膨胀，Token 消耗失控，账单不可预测。
- 难以团队化沉淀：个人的规则、命令、提示词无法沉淀进项目并共享给团队。
OpenCode 用一套统一的设计回应这些问题：
- 模型无关：同一套配置、同一套工作流，可在 Claude、GPT、Gemini、Qwen、本地模型之间自由切换。
- 权限系统：每一类工具（编辑、bash、读文件、联网等）都可以设置为
allow/ask/deny，并支持按命令/路径的细粒度规则。 - 上下文压缩与 Token 优化：内置自动压缩（compaction）、工具输出裁剪（prune）、小模型分流（
small_model）等机制，可显式控制成本。 - 可提交进 Git 的配置：
opencode.json、AGENTS.md、自定义命令、Agent、Skill 都是纯文本文件，可随项目提交、团队共享。
1.3 三种使用形态
OpenCode 提供三种界面，核心能力一致：
- 终端 TUI（主力形态）：在终端里运行
opencode，进入交互式全屏界面。这是功能最完整、最推荐的形态。 - 桌面应用（Desktop App，Beta）：提供 macOS / Windows / Linux 安装包，把 TUI 体验包装成独立窗口应用。
- IDE 扩展 / 无头服务：通过
opencode serve启动本地 HTTP 服务，供编辑器扩展、脚本、CI 调用；并支持 ACP（Agent Client Protocol）、SDK 与 GitHub/GitLab 集成。
无论哪种形态，配置文件、Agent、命令、规则都是通用的——你只需要维护一套配置。
1.4 核心能力速览
- 多模型 / 多 Provider 接入：内置主流提供商，
/connect添加密钥即可用；也支持自定义 OpenAI 兼容端点与本地模型。 - 内置 Agent 体系：两个主智能体 build（默认、全权限）与 plan（只读、规划），三个子智能体 general / explore / scout，可用
Tab切换、用@调用。 - 完整工具集：
bash、read、edit、write、grep、glob、webfetch、websearch、todowrite、skill等，全部受权限系统管控。 - 权限系统：默认全开，可逐项收紧为
ask/deny，并支持按 bash 命令、按文件路径的 glob 细粒度授权。 - 上下文管理：会话快照（snapshot）、
/undo/redo回滚、自动压缩、工具输出裁剪。 - 规则与上下文文件：
AGENTS.md（兼容 Claude Code 的CLAUDE.md）注入项目约定；instructions复用既有规则文件。 - 扩展生态：MCP 服务器（本地/远程）、Agent Skills（
SKILL.md）、插件（Plugin）、自定义工具（Custom Tools）、自定义命令（Command）。 - 协作与可观测：
/share分享会话、opencode stats查看 Token 用量与成本统计、/export导出对话。 - OpenCode Zen：官方精选并调优过的模型网关，开箱即用、按量计费，完全可选。
1.5 与「补全类工具」「闭源 Agent」的区别
OpenCode 既不是 Copilot 那种行内补全，也不是某个厂商封闭的云端 Agent。它的差异点在于：
- 开源、自托管、本地优先：核心运行在你自己的终端/服务器上，代码与配置都在你手里。
- 模型自由：不绑定任何单一模型，可随时切换甚至并用云端与本地模型。
- 配置即代码：所有定制都落在可版本化的文本文件里，可审计、可回溯、可共享。
- 成本可控：把「省 Token」做成一等公民——压缩、裁剪、小模型分流、权限与工具裁剪都有显式开关。
正因为这些特性，OpenCode 特别适合那些既追求效率、又在意成本和可控性的开发者与团队——而这正是本教程「最优化配置」章节要重点解决的问题。
1.6 仓库结构速览
OpenCode 是一个 monorepo，重要内容包括：
- 多语言
README*.md：项目主页说明（含简体中文README.zh.md）。 packages/：核心包，包括 TUI、Web 控制台、文档站点等。packages/web/src/content/docs/：官方文档源文件（本教程主要参考来源）。- CLI 与服务入口：提供
opencode、opencode serve、opencode run等命令。 - 发布产物：npm 包
opencode-ai、各平台二进制与桌面应用安装包。
1.7 本教程的学习路线
本教程共 10 章，建议按顺序阅读：
- 先理解定位与核心概念（第 1 章）。
- 完成安装、
/connect接入模型、/init初始化项目并跑通第一个会话（第 2 章）。 - 熟悉界面、会话管理与内置命令（第 3 章）。
- 吃透配置体系与优先级——这是后续所有定制的基础（第 4 章）。
- 掌握模型与 Provider 配置、变体与本地模型（第 5 章）。
- 学会自定义 Agent 与子代理（第 6 章）。
- 编写自定义命令、规则与上下文、Skill（第 7 章）。
- 配置工具、权限与 MCP 扩展（第 8 章）。
- 重点：系统性地做 Token 优化与省钱配置（第 9 章）。
- 落地完整配置模板、最佳实践与排障（第 10 章）。
如果你的核心诉求是「更省钱、更高效地用 OpenCode」，可以先通读第 4、5、6、9 章，它们构成了「最优化配置」的主线。