02 安装与多形态启动

02 安装与多形态启动

本节摘要:环境就绪后,本节做两件事——把 OpenCode 装上,然后选对启动形态。OpenCode 不是一个「装完只有一种用法」的工具,它有八种入口形态(交互式 TUI、非交互式 run、无头 serve、桌面、Web、嵌入式 SDK、MCP 服务器、ACP、GitHub CI),日常你会反复在两三种之间切换。本节不打算把八种全讲一遍(那是第 3 章的任务),而是帮你建立一个选型框架:给定一个需求,该用哪种形态?把这个判断练熟,你就不会被「八种壳」绕晕。

一、装上它

OpenCode 的安装方式很常规,官方提供了一条命令式的安装脚本,它会自动完成「探测平台 → 下载匹配二进制 → 放到可执行路径」这三步。

# 概念性示例:用官方安装脚本一键装(实际命令以官方说明为准)
# 脚本会自动探测 OS / 架构 / libc / 指令集,挑对平台包
​

装完后,第一条该跑的命令是确认版本:

opencode --version
​

如果它正常返回版本号,恭喜——平台二进制匹配正确,第 01 节那些「非法指令」「找不到符号」的坑你都没踩。如果报错,回到第 01 节的自检清单排查。

💡 开发模式:如果你是想读源码或二次开发,不走安装脚本,而是克隆仓库后用 bun install 装依赖,再以开发模式启动。开发入口是「应用层入口」直接跑 TypeScript(借助 Bun 的原生 TS 能力),不需要先编译。这种方式适合改代码,不适合日常使用。

二、八种形态一览

装好后,你会面对一个选择:用哪种形态?下面这张表先给你一个全景,细节留到第 3 章。

第一次接触,你只需要关心前三种——它们覆盖了绝大多数日常场景。

三、选型框架:给定需求,怎么选

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

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

把这张图印在脑子里。下面用几个典型场景走一遍:

• 「我在终端写代码,想让 AI 帮我改这个函数」 → 交互式 TUI。这是最常见的用法,直接敲启动命令进入全屏对话。
• 「我想在 CI 里让 AI 审一下这个 PR」 → 非交互式 run(或 GitHub CI 形态)。一条命令,拿响应,退出,适合自动化。
• 「我想做一个自己的 AI 编程产品,用 OpenCode 当内核」 → 无头 serve(起 HTTP 服务)或嵌入式 SDK(进程内复用)。前者适合跨进程,后者适合同进程。

⚠️ 新手最常犯的错:不管什么需求都先起 TUI。TUI 是为人机对话设计的,一旦你想自动化,它的交互式特性反而碍事。记住:自动化场景用 run,被调用场景用 serve。

四、第一次启动:TUI 与 run 的对比

为了让你对「形态差异」有实感,这里把最常用的两种(TUI 和 run)的启动方式对比一下。

交互式 TUI——敲下启动命令(无参数即进 TUI),进入全屏对话界面:

opencode
​

它会占据整个终端窗口,你输入一条消息,它流式返回,你可以连续对话、让它读写文件、执行命令。退出时按对应快捷键即可。

非交互式 run——一条命令,拿响应,退出:

opencode run "用一句话解释这个仓库是做什么的"
​

它不进全屏,直接在当前终端打印结果,打印完就退出。适合脚本化调用——你可以在 shell 脚本里把它当一个普通命令用。

这两种形态的内核完全相同,差别只在「外壳」:TUI 是对话外壳,run 是一次性外壳。这个认知非常重要,第 3 章会展开讲「八种形态共享一个内核」。

五、本节没讲的

本节刻意没讲:serve 模式的详细配置(端口、CORS、鉴权)、嵌入式 SDK 的用法、桌面/Web 的安装。这些要么是第 3 章的主题(多形态入口),要么是更后面章节的主题。本节的目标只有一个:让你装好、能选对形态、把最常用的 TUI 和 run 跑起来。

本节要点回顾

1. 安装:官方脚本一键装,自动探测平台挑对二进制;装完用 --version 确认。
2. 开发模式用 bun install + 直接跑 TS,适合改代码不适合日常。
3. 八种形态,第一次只需关心前三种:TUI、run、serve。
4. 选型框架:人在回路 → TUI;只要一次响应 → run;被反复调 → serve;嵌进自己进程 → SDK。
5. 新手坑:别什么需求都起 TUI,自动化场景 TUI 反而碍事。
6. TUI 与 run 内核相同,只差外壳——这个认知是第 3 章「八形态共享内核」的伏笔。

装好了、选对形态了,下一步就是真的跑一次、拿到第一次响应——下一节给你一条最短路径。