OpenCode 介绍与手把手入门教程
收录于 AI 浏览量
开源 AI 编码代理 OpenCode 的上手教程：安装、连接模型、TUI 核心键位、内置 Agent 体系、自定义命令与子代理，一篇走完从零到熟练的路。
AI 编码助手这两年层出不穷，但大多绑死在某一家厂商的客户端里。OpenCode 是一个开源的 AI 编码代理（AI coding agent）：它把“能读写你代码库、能执行命令、能自己多步干活的 AI 助手”做成了一款终端优先的工具，同时提供桌面 App 和 Web 界面。模型随便换——Anthropic、OpenAI、Google 或任何兼容供应商都行，数据和工作流都留在你自己的机器上。
这篇教程带你从安装走到熟练使用，所有命令和键位都以 OpenCode V2 官方文档为准。
它长什么样
OpenCode 的主界面是一个全屏终端应用（TUI）：左边是会话流，右边可以开文件、终端和差异视图。架构上它是客户端-服务端模式——你看到的界面只是客户端，背后有一个后台服务统一管理会话、配置、权限和工具执行。这也意味着桌面端、Web 端和终端可以共享同一套会话。
flowchart LR
A[终端 TUI] --> S[后台服务]
B[桌面 App] --> S
C[Web 界面] --> S
S --> M[模型供应商 API]
S --> T[项目文件与工具执行]
桌面端与 Web 端共用同一套会话。下面是 Web 界面的样子：左侧是对话流，右侧可以实时审查 AI 的每一处改动（Unified/Split 双视图、按文件折叠）。
安装
macOS / Linux 任选一种：
curl -fsSL https://opencode.ai/v2/install | bash
brew install anomalyco/tap/opencode-v2
npm install -g @opencode/cli
也支持 bun、pnpm、yarn、mise、AUR 等，完整列表见官方文档。Windows 用户注意：官方说明 Windows 包管理器暂不受支持，直接从官网下载对应架构的独立压缩包（x64 或 ARM64）解压使用即可。
装完验证：
opencode --version
第一次启动
进入你的项目目录，运行：
opencode
也可以指定其他项目目录：
opencode ~/code/my-project
第一次启动还没有连接任何模型。在 TUI 里输入 /connect，按提示登录你想用的模型供应商（Anthropic、OpenAI、Google 等都有内置支持）。如果不想逐家配置 API key，也可以用官方的 OpenCode Console 托管授权，或者订阅 OpenCode Go（每月 10 美元的套餐，直接用上各家最强编码模型）。
连好模型后，直接在下方的输入框里用自然语言描述任务就行，比如“看一下这个仓库的结构，总结它是做什么的”。终端界面长这样——会话流在上方，输入框在底部，状态栏提示当前 Agent 与模型，右下角常驻三个最常用的键位提示：
必会键位
TUI 的键位体系有一个leader 键（默认 ctrl+x），先按它再按后续字母触发组合键。日常最常用的几个：
| 按键 | 作用 |
|---|---|
ctrl+p | 命令面板，所有功能都能从这里找到 |
shift+tab | 在 Agent 之间循环切换（最常用！） |
ctrl+x 然后 m | 打开模型列表，切换模型 |
ctrl+x 然后 a | 查看 Agent 列表 |
ctrl+x 然后 l | 会话列表 |
ctrl+x 然后 n | 新建会话 |
esc | 中断当前正在跑的任务 |
ctrl+c / ctrl+d | 退出 OpenCode |
ctrl+x 然后 u | 撤销上一条消息（回滚） |
记不住没关系：按 ctrl+p 打开命令面板，一切都有；ctrl+alt+k 还能打开 which-key 面板，按到一半时提示剩余按键。
内置 Agent：先懂“角色”再干活
OpenCode 里的 Agent 是“带特定系统提示、模型偏好和权限约束的角色”。内置四个：
| Agent | 类型 | 用途 |
|---|---|---|
| build | 主 Agent | 默认的编码执行者，可以改文件、跑命令 |
| plan | 主 Agent | 只读探索与规划，不改项目文件，适合先想清楚再动手 |
| general | 子 Agent | 多步研究型任务，工具权限较宽 |
| explore | 子 Agent | 只搜索阅读代码和网页，不写文件 |
典型工作流：先 plan 后 build。按 shift+tab 切到 plan，让它读代码、给出方案；确认方案合理后，再切回 build 让它执行。这比一上来就让 AI 直接改代码稳得多。
非交互用法：脚本与 CI
不想开全屏界面？两条路：
opencode run "解释一下这个仓库是做什么的"
run 直接在终端输出模型结果，适合脚本和 CI。opencode mini 则是一个极简的交互界面，适合 SSH 或小窗口场景。
项目配置：opencode.jsonc
全局配置放在 ~/.config/opencode/opencode.jsonc，项目级配置放在项目根目录的 opencode.jsonc 或 .opencode/opencode.jsonc。一个实用的起步配置：
{
"$schema": "https://opencode.ai/config.json",
"model": "anthropic/claude-sonnet-5-5",
"permissions": [
{ "action": "shell", "resource": "git push *", "effect": "ask" }
]
}
$schema那行让编辑器提供字段补全和校验，建议保留。permissions是有序规则列表：effect取allow（放行）、ask（每次询问）、deny（禁止）；常用 action 有shell、edit、subagent、read、webfetch等。上面的例子表示：执行git push前必须经我确认。
配置文件保存即生效，不用重启；实在没生效就输入 /reload。
自定义命令：把常用提示词变成斜杠命令
建一个 .opencode/commands/review.md：
---
description: 审查代码的正确性与测试覆盖
agent: plan
---
审查 $ARGUMENTS：先列 bug，再列缺失的测试。
之后在 TUI 里输入 /review src/auth.ts，OpenCode 会把模板里的 $ARGUMENTS 替换成你给的参数再提交。还支持位置参数 $1、$2，以及用反引号包住 shell 命令把输出注入提示词：
审查这次改动：
!`git diff --cached`
这样 /review-diff 就会先跑 git diff --cached，把真实差异喂给模型。全局命令放 ~/.config/opencode/commands/，项目命令放 .opencode/commands/，后者优先。
自定义子 Agent：给专项任务立规矩
建一个 .opencode/agents/reviewer.md：
---
description: 只读代码审查，不改任何文件
mode: subagent
permissions:
- action: edit
resource: "*"
effect: deny
- action: shell
resource: "*"
effect: deny
---
审查当前的改动。按严重程度排序输出发现，附文件与行号。
mode: subagent 表示它只能被主 Agent 通过子会话调用（主会话里说“用 reviewer 审查我的改动”即可）；两条 deny 规则保证它只读不写。这类“权限圈死的专职角色”是 OpenCode 最实用的特性之一——让干活的和挑刺的互相独立。
接入 MCP 服务器
一行命令添加远程 MCP 服务器（默认走 OAuth 登录）：
opencode mcp add <名字> --global --url <服务地址>
如果 /mcps 面板里显示需要认证，选中它登录即可，凭据保存在 OpenCode 之外，不会写进配置文件。
出问题了怎么办
- 先看后台服务状态：
opencode service status，卡住了就opencode service restart。 - 怀疑是共享服务的问题，用
opencode --standalone以私有服务模式启动来对比排查。 - 日志在
~/.local/share/opencode/log/opencode.log，role=cli是客户端启动，role=server是会话、供应商、插件等运行时信息。 - 卸载用
opencode uninstall，它会预览将删除的内容；会话数据与配置永远不会被误删。
小结
| 阶段 | 你需要做的 |
|---|---|
| 安装 | 一条 curl / brew / npm 命令 |
| 连模型 | TUI 里 /connect，或用 Console / Go |
| 日常使用 | shift+tab 切 plan/build，ctrl+p 找一切 |
| 进阶 | opencode.jsonc 配权限，commands/ 和 agents/ 定制工作流 |
OpenCode 的设计哲学是“终端优先、模型无关、一切皆可配置”。先用内置的 build/plan 组合跑顺日常任务，再按需加命令、子 Agent 和 MCP，你会发现它越用越贴合自己的工作流。
