# OpenCode 设置

CodeNomad 连接到执行主机上的共享 OpenCode 服务。选择 CLI、更新其文件、重启该服务和重新加载配置是不同操作，彼此不能替代。

## 选择或安装 CLI {#select-cli}

1. 打开**设置 → OpenCode**，使用 **OpenCode 版本**下方的 **OpenCode 可执行文件**卡片选择程序。
2. 保持选中自动条目，以优先使用服务器 PATH（除非其中是较旧的 OpenCode），其次是用户 npm 的 OpenCode 2 安装；也可使用**浏览可执行文件…**，或输入路径并选择**添加**。
3. 使用**检查状态和更新**。如果缺少 OpenCode，选择**安装并启动 OpenCode**；请先检查主机和安装范围。
4. 如果设置流程提供**连接并继续**，请在解决报告的问题后使用它。

安装使用随附 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 版本**卡片中比较**已安装版本**和**运行中的服务**，不要假定选择另一个可执行文件就已替换活动守护进程；**版本详情**列出了最低版本和推荐版本。安装繁忙或可执行文件被锁定时，等待安装程序或进程释放它，检查状态后再重试；不要运行相互竞争的安装程序。

## 必需、推荐和未验证版本 {#versions}

| 分类 | 当前要求 | 含义 |
| --- | --- | --- |
| 最低 | OpenCode **2.2.3** | **图像**设置和 Design 扩展使用的图像生成工具、Code Mode 中 JavaScript 任务的正确执行顺序，以及原生重放和压缩格式；旧版本保存的对话在更新后仍可读取。 |
| 推荐 | OpenCode **2.2.5** | 已验证目标，与技术最低要求不同。 |
| 未验证 | 尚未完整验证的更新版本或自定义版本 | 不会仅因未经测试而拒绝；会检查所连接服务的实际 API 契约。 |

所连接的服务必须提供所需的会话、权限、Form、收件箱和会话环境契约。原生任务计划还会检查计划 API、插件/提供商包和实际生效的 `experimental.schedules` 设置。可用性取决于这些实际使用的能力，也适用于兼容的未来版本。如果设置报告运行中的服务不受支持，请选择/安装受支持的 CLI，并在准备好后显式重启共享服务。

## 主机、WSL 和共享服务范围 {#execution-host}

Windows 上，所选 WSL 可执行文件在其指定发行版中运行。请在那里安装/更新，并使用该发行版内有效的路径。WSL 连接依赖 Windows localhost 转发。Windows CLI 和 WSL CLI 不是可互换的执行环境。

OpenCode 管理其全局服务注册、会话、消息和数据库。CodeNomad 不会按窗口或项目创建私有 OpenCode 数据库。关闭项目标签页会在 CodeNomad 中关闭该项目；会话继续在 OpenCode 中运行，重新打开项目时会再次出现。CodeNomad 绝不会卸载原生 Location。关闭整个窗口、退出或重新加载会保留项目连接以便恢复；这些操作以及关闭后端都不会停止共享守护进程。参阅[项目](projects.md)。

## 保持 OpenCode 运行 {#service-supervision}

在首次启动 Mission 前，**首次启动 Mission 时保持关闭** 可保存显式关闭的选择，无需先安装监管。

在 **设置 → OpenCode** 中，**保持 OpenCode 运行** 会在执行主机上安装系统监管，由使用此服务的所有 CodeNomad 配置共享。它独立于 Missions 运行，即使 CodeNomad 已关闭也有效。若未提前显式关闭，首次启动 Mission 时会启用；创建暂停的 Mission 会保留此选择。暂停、停止或删除 Mission 均保留此偏好。

关闭会移除监管，OpenCode 继续运行但不再被自动重启。如需持续停止，请先关闭此项，再显式停止 OpenCode。监管启用时，`opencode service stop` 后会重新启动。

**运行中 · 监管已生效** 要求系统监管进程活跃且 OpenCode 服务健康。**已安装 · 服务启动中**、**正在安装或移除监管…** 和 **监管失败** 表示不同状态。仅服务有响应，监管仍属未确认。详情会在已知时显示原因、上次尝试、监管进程重试和系统恢复安全检查。**检查监管状态** 只读取；**重试监管** 显式修复请求的安装。未确认的操作会保留原始请求；**重试原始操作** 仅重新发送完全相同的操作。设置版本发生更改时，会刷新以供查看，而非覆盖。

Windows、macOS 和 WSL 在登录后启动。WSL 需要为所选发行版启用 localhost 转发。在原生 Linux 上，linger 会在登录前启动 **所有已启用的用户服务**，并在注销后保持运行。关闭时，仅当 linger 由 CodeNomad 启用且其他监管不再需要时才会恢复；个人设置会保留。如果在没有用户会话打开时恢复 linger 可能导致脱离监管的 OpenCode 进程停止，恢复操作会暂缓，并继续显示 **重试监管**。请在用户会话打开，或脱离监管的 OpenCode 进程退出、可以安全恢复后重试。如果 Linux 需要权限，请在执行主机上授权后重试；请求的偏好仍会保存。睡眠和休眠由操作系统控制。不可用或不受支持的执行主机会显示禁用的控件及说明。

## 更新、重启或重新加载 {#maintenance}

1. 在**设置 → OpenCode**中选择**检查状态和更新**。
2. 若要替换已安装 CLI 文件，在提供时选择**更新到 OpenCode {version}**。等待完成。
3. 检查运行服务状态。只有打算为所有已连接客户端激活所选安装时，才使用**重启共享服务**。
4. 若不安装任何内容而只重启进程，展开**故障排查**，选择**重启 OpenCode 服务**并确认。

| 操作 | 范围与影响 | 安全恢复 |
| --- | --- | --- |
| 更新 CLI | 更改受支持的已安装可执行文件；不会隐式重启运行中的守护进程。 | 失败后检查已安装和运行中两个版本；解决错误后才显式重试。 |
| 重启服务 | 替换共享进程，中断所有已连接 OpenCode 客户端中的活动工作；保留会话历史。 | 健康运行中的原生任务计划会自动恢复；请检查待处理轮次及任何暂停、错误或不确定状态。现有每日条目需要**继续**。请单独检查一次性对话及其恢复控件；参见[任务](missions.md#lifetime)。 |
| 重新加载 OpenCode 配置 | 保留进程，但为所有客户端重建**每个已加载 Location**。取消待处理权限/Form，关闭终端/后台命令；可能中断活动工作。 | 重新加载后检查资源和待处理工作。不要仅因回复丢失而重复提示词或修改操作。 |

已保存配置或已安装插件仍不可用，且可以接受中断时，请显式使用**重新加载 OpenCode 配置**（运行中的服务支持时位于**故障排查**下）。它不是无害的显示刷新。CodeNomad 不会用所选的较旧 CLI 降级正在运行的较新守护进程。

## 会话环境 {#session-environment}

1. 打开**设置 → 高级**并展开**环境变量**。
2. 添加、更改或移除配置文件的覆盖值；每项更改都会立即保存。
3. 通过 CodeNomad 发送下一条提示词、自定义命令或会话 Shell 请求，将当前环境应用到该对话。

这是配置文件范围的设置，在每次发送前由服务器端应用。仅打开/阅读对话或保存设置不会更改原生会话。移除覆盖值会恢复执行主机继承的值；若那里也没有则移除该变量。应用环境失败会阻止发送，而非使用过时值。

此环境控制该原生会话后续的本地 Shell 启动。已运行进程保留其环境。它**不会**重新配置提供商、MCP/LSP 服务器、独立终端或仅属于 Location 的后台 Shell。排队提示词不会各自捕获环境，其他 OpenCode 客户端也可能替换同一会话环境。不要假定完全在 OpenCode 内创建的子会话会收到 CodeNomad 发送时更新。

启动已停止服务时也会传递允许的变量；连接现有守护进程不会更改其进程环境。在 WSL 中，值会与 Linux 执行环境合并，而非 Windows PATH/HOME。更改这些覆盖值不会迁移 OpenCode 数据库或服务注册。

## 编辑原生配置文件 {#configuration-files}

1. 打开**设置 → 配置文件**并选择**文件**。
2. 检查显示路径，编辑后选择**保存**。
3. 使用**重新加载**重读文件；这不是**重新加载 OpenCode 配置**。

此编辑器仅提供其列出的全局 `opencode.json` 和 `opencode.jsonc` 文件，位于 **CodeNomad 服务器用户的** `.config/opencode` 目录下。它不是任意文件编辑器、项目配置选择器，也不保证 WSL/自定义发现目录的守护进程会读取该文件。请通过显示路径验证目标；其他根目录使用守护进程自身工具处理。

保存按文本写入文件；不会验证整个原生配置或重启/重新加载 OpenCode。请与其他客户端协调编辑：此界面不提供外部更改合并。替换大量配置前请保留副本。切换文件或重新加载未保存草稿时，会询问是否丢弃。

针对具体配置的流程请参阅[集成](integrations.md)、[提供商](providers.md)、[任务](missions.md)和 [OpenCode 文档](https://opencode.ai/v2/docs/)。