Table of Contents

OpenCode CLI 和 Desktop 是同一个编码代理产品的客户端。 终端界面适合键盘驱动的工作和脚本。桌面应用提供图形化工作区。重要的比较包括每个客户端背后的服务器、项目、提供商和配置。

先确认后端，再选择界面。 两个 OpenCode 窗口不一定使用同一个服务器或会话。连接到不同服务器的桌面应用属于不同的执行环境，即使模型标签看起来熟悉。

核心要点

  • 终端工作和非交互命令使用 CLI。
  • 图形化工作区使用 Desktop，同时检查所选服务器。
  • 提供商配置决定推理过程，与界面无关。
  • 相同的产品身份不保证不同服务器或版本之间共享会话状态。

范围和日期： 官方文档于 2026 年 10 月 6 日检查。本指南比较界面，不比较模型质量。你需要一个仓库、正常工作的提供商连接和基本终端知识。为试用预留 45 至 60 分钟。

客户端与服务器

OpenCode 将界面与服务器分开。 服务器文档 将终端 UI 描述为客户端，将 opencode serve 描述为独立服务器。这种架构支持多种与代理交互的方式。

Desktop 默认启动本地服务器。 故障排除指南 介绍其 opencode-cli sidecar，以及连接到已配置服务器 URL 的选项。当客户端行为不同时，先检查此连接，再修改提示词。

层要回答的问题
客户端终端 UI、桌面应用还是非交互命令？
代理服务器哪个进程接收请求？
仓库服务器访问哪个目录？
模型提供商哪个服务提供推理？
会话已有对话还是新任务？

服务器位置不等于推理位置。 运行在你电脑上的代理服务器仍会把请求发送到已配置的托管模型。相反，兼容的本地推理服务是独立进程，拥有自己的模型和资源要求。

官方服务器参考将 127.0.0.1 列为 opencode serve 的默认主机名。本地试用时，将服务保持在 loopback：

opencode serve --hostname 127.0.0.1

只有在确定身份验证、防火墙规则以及服务器可访问的仓库路径后，才使用更宽的绑定地址。

连接到代理服务器、仓库文件和独立推理服务的终端与桌面客户端

分别检查代理服务器和推理提供商

终端交互与自动化 

opencode

默认命令会打开终端 UI。 CLI 参考 也记录了程序化命令。在目标仓库中开始，并在请求修改前确认所选代理和模型。

opencode run "Identify this project's test command. Do not modify files."

使用 opencode run 发送有边界的非交互请求。 单独确定适当的权限策略。要求不修改文件可以提供方向，但不会强制文件系统隔离。

当 shell 组合很重要时，选择这种工作流。 可重复的包装器应记录请求、退出状态、相关输出和已修改文件。明确处理失败。空 diff 和成功消息与经过验证的修复需要不同的解释。

Desktop 设置与兼容性

为目标版本使用官方下载页面。 OpenCode 下载页面 列出终端和桌面软件包。在本次检查中，下载页面宣传 v2 终端软件包，而通用文档还包含较旧的安装示例。记录客户端和后端的确切版本，不要混用不同发布轨道的说明。

用一个小型真实任务评估桌面交互。 打开项目，确认服务器，提交有边界的请求，检查已修改文件，并请求修正。评估理解代理操作所需的工作量。不要假设图形客户端完全替代编辑器和调试器。

Desktop 试用预期证据
项目选择代理识别目标仓库
模型选择提供商和模型与试用记录一致
命令执行所需运行时和测试可用
变更检查容易找到并审查完整补丁
重启目标项目和会话仍可识别

配置与模型访问

OpenCode 会合并多个位置的配置。 配置参考 解释优先级和无冲突设置的保留方式。比较有效的模型、代理和权限，而不只是一个项目文件。

提供商访问属于执行设置。 提供商指南 介绍支持的服务和兼容的 endpoints。凭据、endpoint 可达性和模型工具支持都很重要。在其他位置运行的服务器需要自己有效访问提供商和仓库。

客户端不会决定总推理成本。 用相同模型和任务比较计费使用量。包括由配置错误导致的重复运行。使用本地推理时，记录系统内存、模型格式、上下文大小和运行时设置。不要把桌面下载描述成托管计算的免费替代品。

会话与安全切换

验证连续性，不要假设连续性。 切换客户端前记录活动项目和会话。检查目标是否连接到预期服务器并显示预期历史记录。开始新会话时，提供包含目标、已完成工作和剩余检查的简要交接。

避免对同一 checkout 进行并发编辑。 两个计划不同的对话如果指向同一目录，就会共享文件。独立实验使用不同的 worktree 或 checkout。合并变更前先审查。

Handover record
Goal:
Current branch and working directory:
Files changed:
Checks already completed:
Known failures:
Next approved action:

这份记录让交接可检查。 它也能帮助区分界面问题、缺少指令和环境不匹配。不要把凭据放入记录。

服务器访问与权限

将代理服务器视为执行服务。 服务器文档介绍通过 OPENCODE_SERVER_PASSWORD 进行可选身份验证。在跨设备连接前，有意配置访问权限。可访问的代理服务器不等于无害的静态网站。

单独审查工具权限。 权限指南 定义 allow、ask 和 deny 行为。在界面试用期间应用相同策略。检查有效规则前，不要因为客户端提示更少就认为它更安全或更有能力。

从无害的策略测试开始。 在一次性项目中请求允许的文件检查和禁止的编辑。验证观察到的行为，再进行有边界的实施。这样可以测试权限假设。

故障排除与选择

症状首先检查
Desktop 连接失败所选服务器和本地 sidecar 状态
一个客户端缺少模型服务器版本、提供商访问和配置
测试结果不同项目目录和运行时环境
缺少对话服务器和会话身份
加载插件前正常插件配置和版本兼容性

如果脚本请求和 shell 上下文让工作更简单，就选择终端。 如果图形化项目导航改善监督，就选择 Desktop。 将提供商和策略决定与这个偏好分开。

下一步： 在 CLI 汇总 中比较终端替代方案。有关本地推理要求，请阅读 OpenCode 与 Strata 指南 。有关图形化替代方案，请使用 GUI 汇总 。