01 入口矩阵与各自适用场景

01 入口矩阵与各自适用场景

本节摘要:OpenCode 让人困惑的一点是它有八种形态——终端 TUI、桌面应用、浏览器 Web、无头 HTTP 服务器、嵌入式 SDK、MCP 服务器、ACP 服务、GitHub CI。这不是八套代码,而是八个入口共享一个内核。本节先用一张表给你全景,然后给你一个选型框架——给定需求,该用哪种形态?把这个判断练熟,你就不会被「八种壳」绕晕。

一、八种形态全景

先看全貌。八种入口的定位与适合谁:

第一次接触,你只需要关心前三种——它们覆盖了绝大多数日常场景。桌面、Web、SDK、MCP、ACP/CI 是进阶或特定场景的形态。

二、选型框架:三个判断维度

记住三个判断维度,你就能为绝大多数需求选对形态:

是否需要人在回路里持续对话?
   │
   ├─ 是 ──► 交互式 TUI(默认) 或 桌面/Web
   │
   └─ 否(自动化/一次性)
        │
        ├─ 只想要一次响应 ──► 非交互式 run
        │
        └─ 想被别的程序反复调 ──► 无头 serve
                 │
                 ├─ 想嵌进自己进程 ──► 嵌入式 SDK
                 │
                 └─ 想让别的 Agent 用 ──► MCP 服务器
​

三、几个典型场景走一遍

用具体场景感受这个框架:

• 「我在终端写代码,想让 AI 帮我改这个函数」 → 交互式 TUI。最常见用法,直接敲启动命令进全屏对话。
• 「我想在 CI 里让 AI 审一下这个 PR」 → 非交互式 run(或 GitHub CI 形态)。一条命令,拿响应,退出,适合自动化。
• 「我想做一个自己的 AI 编程产品,用 OpenCode 当内核」 → 无头 serve(起 HTTP 服务)或嵌入式 SDK(进程内复用)。前者适合跨进程,后者适合同进程。
• 「我想让另一个 Agent(比如 Claude Code)用 OpenCode 的能力」 → MCP 服务器形态。OpenCode 把自己暴露成一个 MCP server,别的 Agent 连进来。
• 「我想要图形界面,不想用终端」 → 桌面应用。

四、新手最常犯的错

⚠️ 别什么需求都先起 TUI。TUI 是为人机对话设计的,一旦你想自动化,它的交互式特性反而碍事——它会占据终端、等键盘输入、不适合被脚本调用。记住:自动化场景用 run,被调用场景用 serve,被嵌入场景用 SDK,被别的 Agent 用是 MCP server。

五、形态背后的统一性

这一节列了八种形态,但有一个关键认知必须钉死:它们的内核完全相同。TUI 和 run 不是两个产品,serve 和 SDK 也不是——它们是同一个内核的八种「壳」。

                  共享内核
(模式/协议/服务端/领域核心/LLM 抽象)
   │
   ├─► TUI 壳     ├─► run 壳
   ├─► serve 壳   ├─► 桌面壳
   ├─► Web 壳     ├─► SDK 壳
   ├─► MCP 壳     └─► ACP/CI 壳
​

这意味着:不管你用哪种形态,会话循环、工具系统、上下文管理、权限模型都是同一套。你在一个形态里学的知识,完全迁移到其他形态。这就是为什么本教程大部分章节(第 4~9 章)讲内核,不分形态——因为内核是共享的。

六、本节为后续铺路

本节只给你选型框架,没讲每种形态的内部机制。后面三节会挑三个最值得讲的深入:

• 02 平台二进制分发:讲「安装」背后的工程(启动脚本怎么挑对平台包)。
• 03 serve 模式:讲「连接一切」的枢纽(HTTP 服务器的配置与能力)。
• 04 嵌入式 SDK:讲最巧妙的形态(进程内复用内核)。

桌面、Web、MCP server、ACP/CI 的细节散落在更后面章节(第 10 章讲 MCP,第 13 章讲 SDK 与集成)。

本节要点回顾

1. 八种形态:TUI / run / serve / 桌面 / Web / SDK / MCP server / ACP-CI,第一次只关心前三种。
2. 选型三维度:人在回路 → TUI;只要一次响应 → run;被反复调 → serve;嵌进自己进程 → SDK;让别的 Agent 用 → MCP server。
3. 新手坑:别什么需求都起 TUI,自动化场景 TUI 碍事。
4. 内核完全相同:八种形态是同一内核的八种壳,一个形态里学的完全迁移到其他。
5. 本节只给选型,内部机制后面三节挑三个最值得讲的深入(二进制/serve/SDK)。

选型清楚了,下一节讲「安装」背后的工程——启动脚本怎么按平台挑对二进制。