OpenCode 入门：理解客户端-服务器架构与安装
Posted on Thu 01 October 2026 in AI 编程 • Sucre Liu
它和常见的 CLI 工具不一样
第一次用 OpenCode，很多人会把它当成"另一个终端里的 AI 助手"。它能用的，但低估了它：终端界面只是一个客户端，背后有一个常驻的后台服务。
默认情况下，OpenCode 会为你的用户账号发现或启动一个共享服务，你打开的每个本地客户端都连到它。会话、配置、集成、权限、工具执行——这些都归服务管。客户端只负责显示和交互。
理解这一点，后面很多东西就顺了：为什么改配置有时候要重启服务、为什么浏览器客户端需要配 CORS、为什么会有 opencode service 这组命令。本文基于 OpenCode 2.0.12（V2）。
装好之后，先跑起来
opencode
它会在当前目录打开全屏终端界面。想在别的项目里工作，把目录传进去：
opencode ~/code/my-project
OpenCode 自己从当前目录向上查找配置，所以"在哪个目录启动"决定了它读到哪套项目设置。用支持真彩色的终端（Ghostty、WezTerm、Kitty、Alacritty 等）主题颜色最准；不支持时会用近似调色。
三个入口，各管一摊
除了全屏 TUI，它还有两个入口，很多人不知道：
# 一次性提交提示，适合脚本和 CI
opencode run "Explain this repository"
# 极简交互界面，比全屏 TUI 轻
opencode mini
opencode run 是自动化的主力：不打开界面，把提示交出去，等结果回到终端。opencode mini 适合"我就想快速问一句"，或者网络慢、终端窄的时候。
内置的四个代理
OpenCode 默认带了几个可见的 agent，先用起来，别急着建自己的：
| 代理 | 模式 | 用途 |
|---|---|---|
| Build | primary | 默认编码代理，工具默认放行；读敏感环境文件、访问工作区外会先问 |
| Plan | primary | 只探索、只出方案，不改你的项目文件 |
| General | subagent | 研究类、多步任务，工具权限宽，但不能再派生子代理 |
| Explore | subagent | 搜索和阅读代码或网页，不编辑文件 |
这个分工和很多工具"一个万能代理"的思路不同：Plan 负责想，Build 负责做，General/Explore 负责查。 想让它先别动手，就切到 Plan。
连接模型
OpenCode 自带一份来自 models.dev 的 provider 与模型目录。大多数 provider 需要先连接账号：
/connect
/models
先 /connect 选 provider、填凭据，再 /models 选具体模型。选中的模型只作用于当前会话，不会改配置文件——这一点后面配置篇会展开。
服务：出事第一个看的地方
架构带来的直接后果：很多"客户端看着正常但行为诡异"的问题，根子在服务。三个命令要记住：
opencode service status # 看服务信息和状态
opencode api get /api/info # 验证 API 是否健康
opencode service restart # 服务卡住时重启
需要隔离时，可以不带共享服务运行：
opencode --standalone # 私有服务
opencode --server http://localhost:4096 # 连到指定服务
--standalone 在排查"是共享服务的问题还是客户端的问题"时特别有用。
另外有个方便的小命令，能把内部路径打出来给别的工具用：
opencode debug paths db
sqlite3 "$(opencode debug paths db)"
db、home、data、config、cache、state、tmp、bin、log、repos 都支持。注意：它不会启动服务，也不会打开数据库。
卸载也做得比较克制
opencode uninstall --dry-run # 先看会删掉什么
opencode uninstall # 确认删除
想保留配置或数据：
opencode uninstall --keep-config --keep-data
--keep-config 留配置，--keep-data 留会话数据和快照（缓存和状态仍会清）。这种"先干跑、再确认"的设计，在会动用户全局目录的工具里不多见，值得表扬。
关于终端界面
不展开，但几个默认设置值得先知道（它们是 CLI 设置，存在 ~/.config/opencode/cli.json，和项目配置是两回事）：会话标签、diff 视图、系统通知与提示音、键位。这些都属于"个人偏好"，不进项目仓库——下一篇讲配置时会讲清这条边界。
小结
- OpenCode 是客户端-服务器架构：TUI 是客户端，后台服务管会话、配置、权限、工具。
- 三个入口：
opencode（全屏）、opencode mini（轻量）、opencode run（自动化）。 - 四个内置代理：Build 做、Plan 想、General/Explore 查。
- 排障先看服务：
service status→api get /api/info→service restart。
下一篇讲配置：opencode.jsonc 和 cli.json 到底该放什么、两者的优先级怎么算，以及为什么"把项目配置和终端偏好混在一起"是个坑。