在 上一篇文章 中，我们从源码级拆解了 OpenCode 的内部架构——Effect-TS 函数式架构、Session 会话引擎、Agent 循环和工具系统。但架构再精巧，不会用就等于零。OpenCode 作为目前 GitHub 上 55K+ Star 的 AI 编码助手，它的安装、配置和部署流程决定了你能否真正把它用起来。
本文是 OpenCode 系列的第二篇，聚焦于 从代码到运行 的完整链路。覆盖零基础安装、配置文件全面解析、插件系统深入、多 Provider 配置、MCP 集成和生产环境部署。无论你是第一次听说 OpenCode 的新手，还是已经在使用的老用户，这里都有你需要的深度内容。
OpenCode 的部署不像传统 IDE 插件那样 "安装即用"。它基于 Bun 运行时，支持丰富的 Provider 生态，拥有可扩展的插件系统，并能通过 MCP 协议连接外部工具。将这些能力组合起来，是一个需要系统理解的过程。本文就是你的完整路线图。
| 章节 | 内容 | 难度 |
|---|---|---|
| 安装与配置 | Bun 安装、npm 全局安装、首次运行 | 入门 |
| 配置深度解析 | TOML 格式、五大配置域、权限系统 | 进阶 |
| 插件系统 | Loader 架构、V2 钩子机制、开发指南 | 进阶 |
| 多 Provider 配置 | 多模型路由、成本优化、Agent 定义 | 进阶 |
| MCP 集成 | 三种传输模式、服务配置、实战场景 | 高阶 |
| 生产实践 | CI/CD、团队协作、权限安全 | 高阶 |
OpenCode 使用 Bun 运行时，支持 macOS、Linux 和 Windows（通过 WSL）。先安装 Bun：curl -fsSL https://bun.sh/install | bash。然后 npm global 安装：npm install -g opencode。首次运行会在项目根目录创建 .opencode/ 目录。多层配置路径：CLI 参数 > 环境变量 > 项目配置 > 全局配置。
对于 Windows 用户，推荐使用 WSL2 安装。WSL 上先安装 Bun（与 Linux 相同命令），然后全局安装 opencode。需要注意的是，项目文件应该放在 WSL 的 ext4 文件系统（如 /home/user/projects/）而非 Windows 的 NTFS 分区（/mnt/c/），否则会遭遇严重的文件系统性能问题。WSL 的跨文件系统访问延迟可能高达 10-50ms 每次，对 Agent 频繁的文件操作影响巨大。
安装完成后，运行 opencode --help 查看所有命令。核心命令有：opencode（Agent 模式自动执行）、opencode chat（Chat 模式手动确认）、opencode review（代码审查）、opencode session list（会话管理）。了解这些命令的差异是高效使用 OpenCode 的第一步。
| 命令 | 模式 | 适用场景 |
|---|---|---|
| opencode | Agent 模式 | 复杂编码、重构、多文件修改 |
| opencode chat | Chat 模式 | 概念讨论、代码审查、方案设计 |
| opencode review | 审查模式 | PR 自动审查、代码质量检查 |
| opencode session | 管理命令 | 会话列表、恢复、清理 |
TOML 格式配置文件位于 .opencode/config.toml。五大配置域：全局设置（默认模型）、Provider 配置（API Key 与模型路由）、Agent 定义（角色与权限）、工具权限（allow/ask/deny）、插件声明。源码 Schema 定义在 packages/core/src/config/ 目录下，共 19 个文件。
全局设置是最基础的配置项。你可以设置 default_model = "anthropic:claude-sonnet-4-20250514" 作为首选模型，设置 max_tokens = 64000 控制输出长度上限。Auto compaction 机制（auto_compaction = true 配合 compaction_target = 32000）会在上下文接近限制时自动压缩历史消息，避免突然中断工作流。
权限系统是最关键的安全防线。OpenCode 支持三级权限：allow（自动允许）、ask（执行前询问）、deny（禁止）。默认权限策略是 *:* → allow，但生产环境建议收紧为：文件编辑允许、Shell 命令询问、敏感文件禁止。可以为不同 Agent 设置不同的权限域，实现细粒度控制。
Plugin Loader 实现位于 packages/opencode/src/plugin/loader.ts，4 个核心阶段：resolve（解析插件声明）→ check（检测入口文件）→ load（动态 import）→ apply（注册钩子函数）。V2 插件采用钩子机制：catalog.transform、aisdk.sdk、aisdk.language。
编写自定义插件的第一步是理解钩子系统。Hook 是插件与核心引擎之间的契约点。catalog.transform 钩子允许插件修改 Provider 配置列表（用于动态注入 Provider）；aisdk.sdk 钩子用于注册自定义 AI SDK；aisdk.language 钩子用于添加语言支持。这些钩子在 Effect 的 Gen 函数中注册，Effect-TS 确保类型安全和错误传播。
自定义 Provider 插件是最常见的插件类型。你只需实现一个 ProviderPlugin 接口，定义 id、label、model 列表和 api_key 配置。插件可以发布到 npm，团队内部通过 .opencode/config.toml 的 [[plugins]] 部分声明即可使用。插件版本通过 engines 字段与 OpenCode 核心版本绑定。
同时配置 OpenAI、Anthropic、Google 等多个 Provider，根据场景灵活切换。模型标识符格式：providerID:modelID。路由由 ConfigProviderPlugin 通过 catalog.transform 钩子注入。可为每个模型设置成本属性，实现多模型策略优化。
一个典型的多模型策略是"三级路由"：fast 层使用 openai:gpt-5-mini 进行搜索和简单查询（成本最低），coding 层使用 anthropic:claude-sonnet-4-20250514 进行主要的编码工作（性能最佳），review 层使用 anthropic:claude-opus-4 进行代码审查（最严格）。工作中通过 /agent fast 或 /agent coding 随时切换，无需重启会话。
成本优化是生产环境的核心关注点。通过为每个模型设置 cost.input 和 cost.output（单位：每百万 token 的美元价格），OpenCode 可以实时追踪 Token 消耗并生成成本报表。建议为团队设置月度预算告警，当 Token 消耗超过预算的 80% 时自动通知管理员。
OpenCode 实现 MCP 客户端，位于 packages/opencode/src/mcp/index.ts（910 行）。支持 3 种传输：StdioClientTransport（本地进程）、StreamableHTTPClientTransport（远程 HTTP）、SSEClientTransport（远程 SSE 回退）。可连接 Playwright MCP、PostgreSQL MCP、GitHub MCP 等。
MCP 集成让 OpenCode 从一个"编码助手"升级为"全栈工具平台"。连接 Playwright MCP Server 后，OpenCode 可以在浏览器中执行操作（截图、点击、表单填写），实现端到端测试自动化。连接 PostgreSQL MCP Server 后，OpenCode 可以直接查询数据库、创建迁移脚本、分析数据模式。GitHub MCP 则让 OpenCode 可以管理 Issue、创建 PR、审查代码。
MCP 配置在 .opencode/config.toml 的 [mcp.servers] 部分。每个服务器配置包括类型（local 或 remote）、启动命令或 URL、以及环境变量。多个 MCP 服务器可以同时运行，OpenCode 会自动合并所有服务器的工具列表。注意 MCP 服务器的启动顺序——依赖关系会导致某些工具暂时不可用。
CI/CD 集成：GitHub Actions 中运行 opencode review 实现 PR 自动审查。分层配置共享：团队共享 Agent 定义和权限模板（Git 追踪），个人偏好存全局配置，API Key 用环境变量。严格权限规则：仅允许 src/** 编辑、npm run * 和 git *。
团队协作的最佳实践是将 Skills 和配置模板纳入 Git 仓库。在项目根目录创建 .opencode/ 目录并 Git 追踪，团队所有成员共享 Agent 定义、权限模板和自定义 Skills。个人偏好（如主题颜色、编辑器设置）则存储在全局配置中不提交。API Key 通过环境变量注入，绝不应出现在配置文件中。
性能优化建议：确保 .gitignore 文件中排除了 node_modules、dist、.next 等大目录（OpenCode 会遵守 gitignore 规则）。对于大型 monorepo，使用 search.max_results = 50 和 search.max_file_size = 100000 限制搜索范围。设置 max_steps = 100 防止 Agent 无限循环。生产环境建议将 bash = "ask" 作为默认权限。