OpenCode Desktop 和 CLI 怎么选?接入、切换与排错指南
按实际任务比较 OpenCode 桌面版和 CLI,说明模型接入、会话切换和版本差异,并提供可下载的小练习与故障排查方法。
想在可视化工作区中管理会话、查看代码改动,先选 OpenCode Desktop;工作从终端、远程 Shell 或可重复执行的脚本开始,先选 CLI。 两者可以一起用,但能否正确衔接,取决于项目目录、服务和模型是否一致,不能只看是否登录了同一个账号。
本文比较的是 OpenCode 的两种界面。如果你在比较 OpenCode 与 OpenAI Codex,请阅读 OpenCode 与 Codex CLI 对比。
我们在 2026 年 11 月 17 日核对了当前文档,在隔离目录安装 OpenCode CLI 2.3.0,检查版本和帮助输出,并在本地运行了文中练习的 Python 测试。没有进行付费模型对比,也没有在 Desktop 中完成该练习。 下文的界面行为来自文档,不代表某种界面写代码更好的实测结论。本文由提供 API 接入服务的 Ofox 发布。
按你要完成的任务选择
| 下一步要做什么 | 从哪里开始 | 选择依据 | 需要核对 |
|---|---|---|---|
| 浏览本地仓库并检查多处改动 | Desktop | 可视化会话与差异查看适合以审查为主的工作 | 打开正确目录,接受改动前检查文件 |
| 通过 SSH 在开发机上工作 | CLI | 可以直接从已有的远程 Shell 开始 | 凭证、文件和工具必须位于那台机器上 |
| 在脚本或 CI 中重复执行提示词 | CLI | opencode run 无须打开交互界面 | 模型、权限、输出处理与失败状态 |
| 喜欢键盘操作,也需要交互对话 | CLI TUI | CLI 本身也是交互应用,不只是脚本命令 | 终端显示与当前项目 |
| 同一个本地任务中途切换界面 | 均可,但要明确交接 | 当前 V2 支持共享本地服务 | 两端确实连接同一服务、使用同一项目 |
| 处理鉴权或提供商错误 | 先查连接 | 换界面不会修复无效密钥或不受支持的请求 | 精确的提供商、模型、端点和错误信息 |
OpenCode 产品页(英文)将 Desktop 描述为带有会话、标签页和差异查看的工作区,将 Terminal 描述为可从 Shell 或远程服务器使用的界面。这些是有用的工作方式差异,并不证明底层模型的能力不同。
例如,你已经在 SSH 中查看测试失败,转到文件系统不同的本地 GUI,未必更方便;如果主要在本地审查多处修改,把对话和代码差异放在可视化工作区中可能更顺手。无论选哪种,都仍需运行项目测试。
跟着教程配置前,先核对版本
“Desktop 还是 CLI”和“OpenCode 1 还是 OpenCode 2”是两个不同问题。版本不一致,很容易被误判为界面能力有限。
先在终端运行:
opencode --version
opencode --help
opencode run --help
我们的隔离安装返回 opencode v2.3.0,帮助列出 run、session、service、models、auth 和 debug。这个版本的 opencode models 不接受提供商名称作为位置参数,不能假定旧教程中的命令在当前程序中仍有效。
对于 macOS 或 Linux 上通过 npm 全新安装 V2 的情况,当前安装文档(英文)列出:
npm install -g @opencode/cli
opencode --version
已有 V1 的用户先阅读官方迁移指南(英文)。两代都使用 opencode 命令,直接再装一个包可能覆盖现有命令或造成冲突。Windows 用户应使用 OpenCode 列出的独立 CLI 下载,不要默认这些包管理器步骤同样适用。Desktop 也提供 macOS、Windows 和 Linux 下载。
V2 继续兼容受支持的 V1 配置,并不要求升级时重写所有文件;但插件和服务端集成存在破坏性变更。V2 原生提供商条目使用 providers、package、settings,旧条目使用 provider、npm、options。每个嵌套提供商条目应保持一种完整格式,不能拼接搜索摘要中的两代字段。转换已能工作的配置前,先备份。
连接提供商后,还要选择模型
接入有三个独立检查点:提供商已连接、模型可见、请求真正成功。第一步通过,不能证明后两步也通过。
Ofox 用户可以从 OpenCode 接入文档开始,其中包含两种界面的路径。按 API Key 鉴权说明获取密钥,不要把它放进提交到仓库的项目文件、截图或复制出来的诊断日志。
Desktop 的操作路径
Ofox 文档给出的流程是:
- 打开 Settings → Providers,选择 Show more providers。
- 搜索 Ofox,连接并输入密钥。
- 打开 Settings → Models,搜索 Ofox,启用目标模型。
- 在正确项目中创建会话,在会话模型选择器中选中它。
如果实际界面不同,先核对安装版本和当前提供商设置入口,不要立即判断账号有问题。下图记录的是英文 Ofox 文档页面,不是本次 Desktop 推理测试截图。

文档截图采集于 2026 年 11 月 17 日。内嵌界面属于文档示例,不能据此判断你电脑上的安装版本。
CLI 的操作路径
打开项目目录,启动 opencode,在交互界面中用 /connect 选择提供商,再用 /models 选择模型。这些斜杠命令应在应用内部输入,不是在普通 Shell 提示符后输入。
脚本场景先用 opencode models 查看模型列表,再使用返回的精确标识符:
opencode run --model 'PROVIDER/MODEL' "Explain the files in this project. Do not edit them."
必须替换 PROVIDER/MODEL,它只是占位符,并非真实模型。上述英文提示要求说明项目文件且不作修改。此命令会发送模型请求,可能产生提供商费用;我们只通过本地帮助核对参数,没有执行这条请求。
内置 Ofox 提供商满足需要时,优先使用它。自定义提供商是针对特定协议或端点的另一条路径,并不是使用桌面版的前提。内置与自定义提供商说明解释了区别。需要自定义路径时,将当前 OpenCode 提供商参考(英文)与 Ofox 文档的精确端点、支持协议对应起来。OpenCode 自定义 API 配置教程说明了提供商和模型注册的关系,但其中带日期的版本示例仍须按实际安装版本核对。
切换界面时,哪些状态能够共享?
当前 CLI 文档(英文)描述了面向本地用户的共享后台服务,由它管理会话、配置、权限、集成和工具执行。CLI 也可以通过 --standalone 使用私有服务,或通过 --server 连接指定服务。
因此,“在同一台笔记本上”不足以证明交接正确。私有服务、不同账号、远程主机或不同项目路径,都可能对应不同的工作上下文。
| 项目 | 交接时检查什么 | 为什么要查 |
|---|---|---|
| 文件 | 确认绝对项目路径和当前文件内容一致 | 同名文件夹可以包含不同工作 |
| 服务 | 确认两端连接预期服务 | 私有或远程服务不会自动等于本地共享服务 |
| 会话 | 选中目标会话,而非只选最新的 | 最近历史可能属于另一个任务 |
| 模型 | 对照精确的提供商与模型选择 | 熟悉的显示名称不能证明请求路由相同 |
| 权限 | 检查任务允许读取、修改和执行什么 | 切换界面不等于授权扩大访问范围 |
| 工具与环境 | 检查真正执行操作的机器上的工具 | 本地安装 Python 不代表远程主机也有 |
要检查服务状态,又不重启正在进行的工作,可以使用:
opencode service status
opencode session list
在要继续的项目目录中执行会话命令。CLI 2.3.0 的本地帮助将其描述为列出当前项目的顶层会话;我们验证了命令定义,没有完成跨界面会话迁移测试。
配置不一致时,按配置参考(英文)检查相关项目和用户配置位置。托管设置可能具有更高优先级,不应为了让两个界面看起来一致而关闭管理策略。
用独立工作副本完成同一个小任务
下载对比练习包。其中包含故意未完成的 Python 函数、四项测试、提示词和编辑编写的参考解法。文件说明与提示词为英文;单独运行测试不需要 API Key,也不需要安装依赖。
任务是接受以 .csv 结尾的文件名、不区分大小写,同时拒绝 .csv.tmp 等后缀。它只是一个范围很小的编程练习,不是软件工程能力基准。
- 将压缩包解压两次,分别放入
desktop-check和cli-check等独立目录。 - 在两个目录中分别运行
python3 -m unittest -v。如果系统使用python启动 Python 3,则改用该命令。 - 初始版本应当是四项测试中两项失败。引入 Agent 前先记录基线。
- 在 Desktop 中打开
desktop-check;从cli-check启动 CLI。使用相同提供商、模型和等效权限设置。 - 给两端同一段提示词。下面保留练习包中的英文原文,要求只改函数、不改测试,并报告真实测试结果:
Read app.py and test_app.py. Update only accepts_csv in app.py so filenames
ending in .csv are accepted case-insensitively. Reject .csv.tmp and names
with no .csv suffix. Do not modify the tests or install dependencies.
Run python3 -m unittest -v and report the result. If Python is unavailable,
say so rather than claiming the tests passed. Explain the exact code change.
每轮运行后检查 app.py,确认 test_app.py 没有变化。自行重跑测试,预期四项全部通过;一句“已经修好”不等于验收结果。参考解法用于核对预期规则,不是任一 OpenCode 界面生成的输出。
我们已在本地确认初始版本两项失败、参考解法四项通过,没有采集 Desktop 与 CLI 的耗时、费用或模型成功率。如果你执行这个练习,应将这些观察与确定性的测试结果分开记录。小任务可以帮助判断操作方式是否顺手,不能证明某种界面普遍更快或更准确。
如果要测试交接,先停止正在进行的工作,再切换界面,逐项核对上一张表中的六个项目后继续。不要在对比时让两个 Agent 同时修改同一工作副本,否则改动会互相干扰。
按出问题的层级排查
| 现象 | 先查什么 | 下一步 |
|---|---|---|
找不到 opencode | 安装方式与 Shell PATH | 核对该版本的安装方法;PATH 变化后重新打开 Shell |
| 复制的命令不接受参数 | opencode --version 与该命令的 --help | 使用当前安装代际的语法,不要先更换凭证 |
| 提供商已连接但模型不显示 | 模型可见性、提供商 ID、模型 ID | 检查 Desktop 中是否启用模型及 CLI 模型列表;使用自定义注册时再核对注册 |
| Desktop 能看到会话,CLI 看不到 | 项目路径、账号和服务 | 从正确项目列出会话,核对服务状态 |
| 请求返回 401 | 凭证来源与目标端点 | 按 Ofox 鉴权与请求错误说明检查,不在问题报告中粘贴密钥 |
| 请求返回 429 | 速率限制与返回的重试信息 | 阅读 429 重试排查,换界面不会消除限制 |
| 普通聊天成功,Agent 工具失败 | 模型能力、协议和工具结果格式 | 按 OpenAI 兼容 API 检查方法(英文)区分普通聊天与工具调用兼容性 |
如果问题涉及升级,记录旧版、新版和第一个失败的操作,每次只改一个变量。同时重装应用、替换密钥和重写提供商配置,会让你难以判断哪项改动真正起作用。
本地可视化审查先选 Desktop,终端与脚本工作先选 CLI;确实需要交接时再同时保留两者。成功的标准是文件、模型和权限正确,结果可以自行验证,而不是界面看起来更强大。


