CodeNomad OpenCode 设置
CodeNomad 连接到执行主机上的共享 OpenCode 服务。选择 CLI、更新其文件、重启该服务和重新加载配置是不同操作，彼此不能替代。
选择或安装 CLI
- 打开设置 → OpenCode，使用 OpenCode 版本下方的 OpenCode 可执行文件卡片选择程序。
- 保持选中自动条目，以优先使用服务器 PATH（除非其中是较旧的 OpenCode），其次是用户 npm 的 OpenCode 2 安装；也可使用浏览可执行文件…，或输入路径并选择添加。
- 使用检查状态和更新。如果缺少 OpenCode，选择安装并启动 OpenCode；请先检查主机和安装范围。
- 如果设置流程提供连接并继续，请在解决报告的问题后使用它。
安装使用随附 Node/npm，进行与其他客户端共享的标准用户安装。为用户安装并配置 PATH会更改该用户的终端设置；之后请打开新终端。浏览器连接的是 CodeNomad 服务器：其文件选择器和可执行文件选择针对该服务器，而非浏览设备。
当 PATH 中排在最前面的是较旧的 OpenCode 时，提供的操作取决于其安装方式。对于通过 npm 安装的 OpenCode 1.x，用 OpenCode 2 替换 OpenCode {version} 会请求确认，移除该 npm 软件包，并在同一 npm 文件夹中安装 OpenCode 2；OpenCode 数据文件夹会保留，OpenCode 2 会自行导入 1.x 的对话。以其他方式（winget、Homebrew、手动）安装的较旧或不可用的 OpenCode 绝不会被修改：为 CodeNomad 安装 OpenCode 2 会在其旁边的用户 npm 文件夹中安装 OpenCode 2，之后 CodeNomad 使用该副本。如果该旧命令本身位于用户 npm 文件夹中（例如 ~/.local/bin 中的链接），或该文件夹不可写，设置会说明原因，而不提供此操作：移动或重命名该命令，或修复文件夹权限，然后选择检查状态和更新。终端中的 opencode 命令可能仍会启动旧版本。显式选择的自定义可执行文件绝不会被替换。
已安装可执行文件和正在运行的服务可能版本不同。请在 OpenCode 版本卡片中比较已安装版本和运行中的服务，不要假定选择另一个可执行文件就已替换活动守护进程；版本详情列出了最低版本和推荐版本。安装繁忙或可执行文件被锁定时，等待安装程序或进程释放它，检查状态后再重试；不要运行相互竞争的安装程序。
必需、推荐和未验证版本
| 分类 | 当前要求 | 含义 |
|---|---|---|
| 最低 | OpenCode 2.1.2 | Code Mode 中 JavaScript 任务的正确执行顺序，以及 2.1 的原生重放和压缩格式；旧版本保存的对话在更新后仍可读取。 |
| 推荐 | OpenCode 2.1.4 | 已验证目标，与技术最低要求不同。 |
| 未验证 | 尚未完整验证的更新版本或自定义版本 | 不会仅因未经测试而拒绝；会检查所连接服务的实际 API 契约。 |
所需的会话、权限、Form、收件箱和会话环境契约也必须可用。仅有可执行文件版本并不能证明所连接服务支持它们。如果设置报告运行中的服务不受支持，请选择/安装受支持 CLI，并在准备好后显式重启共享服务。
主机、WSL 和共享服务范围
Windows 上，所选 WSL 可执行文件在其指定发行版中运行。请在那里安装/更新，并使用该发行版内有效的路径。WSL 连接依赖 Windows localhost 转发。Windows CLI 和 WSL CLI 不是可互换的执行环境。
OpenCode 管理其全局服务注册、会话、消息和数据库。CodeNomad 不会按窗口或项目创建私有 OpenCode 数据库。关闭项目标签页会在 CodeNomad 中关闭该项目；会话继续在 OpenCode 中运行，重新打开项目时会再次出现。CodeNomad 绝不会卸载原生 Location。关闭整个窗口、退出或重新加载会保留项目连接以便恢复；这些操作以及关闭后端都不会停止共享守护进程。参阅项目。
更新、重启或重新加载
- 在设置 → OpenCode中选择检查状态和更新。
- 若要替换已安装 CLI 文件，在提供时选择更新到 OpenCode {version}。等待完成。
- 检查运行服务状态。只有打算为所有已连接客户端激活所选安装时，才使用重启共享服务。
- 若不安装任何内容而只重启进程，展开故障排查，选择重启 OpenCode 服务并确认。
| 操作 | 范围与影响 | 安全恢复 |
|---|---|---|
| 更新 CLI | 更改受支持的已安装可执行文件；不会隐式重启运行中的守护进程。 | 失败后检查已安装和运行中两个版本；解决错误后才显式重试。 |
| 重启服务 | 替换共享进程，中断所有已连接 OpenCode 客户端中的活动工作；保留会话历史。 | 重新连接并检查对话和计划任务；重启不代表自动继续。 |
| 重新加载 OpenCode 配置 | 保留进程，但为所有客户端重建每个已加载 Location。取消待处理权限/Form，关闭终端/后台命令；可能中断活动工作。 | 重新加载后检查资源和待处理工作。不要仅因回复丢失而重复提示词或修改操作。 |
已保存配置或已安装插件仍不可用，且可以接受中断时，请显式使用重新加载 OpenCode 配置（运行中的服务支持时位于故障排查下）。它不是无害的显示刷新。CodeNomad 不会用所选的较旧 CLI 降级正在运行的较新守护进程。
会话环境
- 打开设置 → 高级并展开环境变量。
- 添加、更改或移除配置文件的覆盖值；每项更改都会立即保存。
- 通过 CodeNomad 发送下一条提示词、自定义命令或会话 Shell 请求，将当前环境应用到该对话。
这是配置文件范围的设置，在每次发送前由服务器端应用。仅打开/阅读对话或保存设置不会更改原生会话。移除覆盖值会恢复执行主机继承的值；若那里也没有则移除该变量。应用环境失败会阻止发送，而非使用过时值。
此环境控制该原生会话后续的本地 Shell 启动。已运行进程保留其环境。它不会重新配置提供商、MCP/LSP 服务器、独立终端或仅属于 Location 的后台 Shell。排队提示词不会各自捕获环境，其他 OpenCode 客户端也可能替换同一会话环境。不要假定完全在 OpenCode 内创建的子会话会收到 CodeNomad 发送时更新。
启动已停止服务时也会传递允许的变量；连接现有守护进程不会更改其进程环境。在 WSL 中，值会与 Linux 执行环境合并，而非 Windows PATH/HOME。更改这些覆盖值不会迁移 OpenCode 数据库或服务注册。
编辑原生配置文件
- 打开设置 → 配置文件并选择文件。
- 检查显示路径，编辑后选择保存。
- 使用重新加载重读文件；这不是重新加载 OpenCode 配置。
此编辑器仅提供其列出的全局 opencode.json 和 opencode.jsonc 文件，位于 CodeNomad 服务器用户的 .config/opencode 目录下。它不是任意文件编辑器、项目配置选择器，也不保证 WSL/自定义发现目录的守护进程会读取该文件。请通过显示路径验证目标；其他根目录使用守护进程自身工具处理。
保存按文本写入文件；不会验证整个原生配置或重启/重新加载 OpenCode。请与其他客户端协调编辑：此界面不提供外部更改合并。替换大量配置前请保留副本。切换文件或重新加载未保存草稿时，会询问是否丢弃。
针对具体配置的流程请参阅集成、提供商、任务和 OpenCode 文档。