OpenCode 完全指南总目录

这是「OpenCode 完全指南」系列的总目录。本系列整合了 OpenCode AI 编程助手的所有核心功能，形成 14 篇系统性学习指南。无论你是刚接触 OpenCode 的新手，还是希望深入挖掘高级功能的老用户，这里都有你需要的内容。

系列文章列表

第一篇：OpenCode 安装入门与基础概览

适合：所有新用户

OpenCode 是什么，能做什么
一键安装脚本和包管理器安装
桌面版（macOS / Windows / Linux）安装
首次运行配置（选择模型提供商、设置 API Key）
TUI 终端界面导览
Build 与 Plan 双模式介绍
核心功能速览和目录结构

第二篇：opencode.json 配置文件完全指南

适合：需要深度定制的用户

配置文件层级（项目级、全局级、默认值）
合并策略和优先级
完整配置项解析（14 大类）
环境变量引用语法 ${VAR}
生产级完整配置示例
配置验证命令

第三篇：主题、界面与快捷键定制

适合：追求个性化体验的用户

内置主题一览与切换
完整自定义主题配色方案
TUI 界面详细配置（布局、显示、代码、输入）
快捷键绑定完整列表和自定义方法
终端字体推荐
终端兼容性注意事项

第四篇：Agent 与 Sub-Agent 系统完全指南

适合：需要多角色协作的高级用户

Agent 的架构概念
Build Agent vs Plan Agent 详解
内置 General Sub-Agent
自定义 Agent 编写（权限、工具、Skills）
Sub-Agent 并行调度原理
完整 Agent 团队配置示例
并行与串行任务的最佳实践

第五篇：Skills 技能系统完全指南

适合：想将专业知识固化为可复用模块的用户

Skill 概念和目录结构
内置 Skills 全览（开发流程、代码质量、前端设计等）
SKILL.md 编写规范和模板
外部脚本和资源引用
自动触发机制
链式 Skills 和条件化 Skills
从 Superpowers 社区获取 Skills

第六篇：Rules 规则与指令系统

适合：所有需要规范 AI 行为的用户

规则文件体系（AGENTS.md、CLAUDE.md、instructions.md）
AGENTS.md 完整编写模板
行为指令（条件、约束、安全）
提示词工程技巧（角色、格式、约束、分步）
auto_prompt.md 自动记忆
完整的团队项目规则文件参考

第七篇：MCP 服务器完全指南

适合：想让 AI 接入外部工具的用户

MCP（Model Context Protocol）概念
stdio 与 SSE 两种传输协议
官方 MCP 服务器详解（Filesystem、GitHub、PostgreSQL、Puppeteer 等）
实战场景：数据库查询、GitHub 工作流、端到端测试、网络搜索
TypeScript / Python 自定义 MCP 服务器开发
调试与故障排查

第八篇：Provider 与模型配置

适合：需要选择/切换模型的用户

75+ 提供商全景图
商业模型（Claude、GPT、Gemini、DeepSeek 等）配置
多模型切换和参数调优
本地模型搭建（Ollama、LM Studio）
OpenCode Go 订阅服务
Token 管理和成本控制策略
Policies 策略系统

第九篇：自定义命令 Commands

适合：想将重复操作一键化的用户

内置命令完整列表
自定义命令编写（参数、上下文引用）
实用命令分类（开发、测试、部署、文档）
高级技巧（条件执行、链式命令、交互式命令）
跨项目命令复用
高效命令集推荐

第十篇：CLI 命令行与自动化

适合：CI/CD 和自动化场景

CLI 命令大全
非交互模式 -p 参数详解
管道输入和文件引用
自动化脚本编写（质量门禁、Release Notes、每日审查）
GitHub Actions CI/CD 集成
GitLab CI 集成
Pre-commit Hook、Docker 集成
批量处理和最佳实践

第十一篇：权限与安全完全指南

适合：关注安全的用户和团队

权限模型（编辑、命令执行、网络访问）
路径级别精细控制（allow / deny / ask）
Shell 命令和网络域名白名单
Policies 策略系统
敏感信息保护和自动检测
不同环境的安全配置模板
审计日志
6 大安全最佳实践

第十二篇：工具、插件与扩展系统

适合：需要扩展 OpenCode 能力的开发者

13 个内置工具详解
自定义工具开发（TypeScript）
完整的插件系统（结构、清单、生命周期）
Hooks 系统（8 个生命周期事件）
SDK 编程式控制
Formatters 代码格式化

第十三篇：项目协作与工作流集成

适合：团队使用场景

GitHub / GitLab 深度集成
GitHub App 和 MCP 方式对比
LSP 服务器配置（TypeScript、Rust、Go、Python 等）
References 跨项目引用
上下文窗口管理策略
会话分享与协作
团队标准化配置模板
Code Review 工作流
TDD 和探索模式工作流

第十四篇：调试、网络与故障排除

适合：遇到问题时查阅

调试模式和日志分析
opencode doctor 诊断工具
HTTP 代理配置（Clash、V2Ray、企业代理）
10 个常见问题排查方案
性能优化（启动速度、响应速度、内存）
系统化调试方法
Bug Report 模板和获取帮助渠道

学习路线图

新手路线（1-2 天）

第1步：第一篇 → 安装和基础了解
第2步：第二篇 → 了解配置文件结构
第3步：第八篇 → 选择和配置模型
第4步：开始实际使用 OpenCode 编程

进阶路线（1 周）

在完成新手路线的基础上：
第5步：第六篇 → 创建项目 AGENTS.md 规则
第6步：第九篇 → 编写常用自定义命令
第7步：第四篇 → 理解 Agent 系统，创建自定义 Agent
第8步：第十二篇 → 配置 Formatters 和 Hooks
第9步：第三篇 → 定制主题和快捷键

专家路线（2 周）

在完成进阶路线的基础上：
第10步：第五篇 → 编写自定义 Skills
第11步：第七篇 → 接入 MCP 服务器扩展开态
第12步：第十篇 → 集成 CI/CD 自动化流水线
第13步：第十三篇 → 建立团队协作标准
第14步：第十一篇 → 配置安全策略和审计
第15步：第十四篇 → 掌握故障排查（备用）

按场景查阅

我是一个人开发

优先阅读：第一篇 → 第二篇 → 第八篇 → 第六篇 → 第九篇

重点：配置好模型、写好 AGENTS.md 规则、创建常用命令加速开发

我在团队中使用

优先阅读：第一篇 → 第十三篇 → 第六篇 → 第十一篇 → 第四篇

重点：团队标准配置、GitHub 集成、安全策略、多 Agent 分工

我想最大程度自定义

优先阅读：第二篇 → 第三篇 → 第十二篇 → 第五篇 → 第七篇

重点：深度定制配置文件、插件开发、Skill 编写、MCP 扩展

我遇到了问题

优先阅读：第十四篇 → 第二篇

重点：opencode doctor 诊断、日志分析、常见问题排查

快速查找表

| 我想做... | 看哪篇 |
|-----------|--------|
| 安装 OpenCode | 第一篇 |
| 接入 Claude/GPT/DeepSeek | 第八篇 |
| 搭建本地模型 | 第八篇（Ollama 部分） |
| 配置代理上网 | 第十四篇 |
| 让 AI 遵守团队规范 | 第六篇 |
| 创建一键部署命令 | 第九篇 |
| AI 修改后自动格式化代码 | 第十二篇（Formatters 部分） |
| 控制 AI 不能看 .env 文件 | 第十一篇 |
| 接入数据库查询 | 第七篇 |
| 创建代码审查 Agent | 第四篇 |
| 让 AI 学会公司内部规范 | 第五篇 |
| 集成 GitHub Actions | 第十篇 |
| 自定义终端主题配色 | 第三篇 |
| 修改快捷键 | 第三篇 |
| 减少 Token 消耗 | 第八篇（Token 管理部分） |
| 分享会话给同事 | 第十三篇 |
| 排查连接失败问题 | 第十四篇 |

关于本系列

本系列将原有博客中约 100 篇 OpenCode 相关文章进行归类、去重和整合，形成 14 篇结构化、系统化的完全指南。每篇文章覆盖一个完整的主题领域，从概述到配置，从示例到最佳实践，方便查阅和深入学习。

Happy coding with OpenCode!