CodeNomad CodeNomad 帮助
本指南介绍如何将当前 CodeNomad 桌面或浏览器工作区与 OpenCode 服务配合使用，重点说明 CodeNomad 的控件、执行边界和恢复方式，而非 OpenCode 配置教程或版本归档。
请先阅读
CodeNomad 将工作区连接到一个共享的 OpenCode 后台服务。会话和消息属于 OpenCode；标签页、输入框草稿和布局属于 CodeNomad 客户端。关闭标签页会在 CodeNomad 中关闭该项目，但会话继续在 OpenCode 中运行，重新打开项目即可再次找到。关闭 CodeNomad 也不等于停止 OpenCode。
- 查看主机要求和 OpenCode 设置。
- 打开项目，然后选择对话的智能体、模型和思考控件。
- 更改凭据、重启服务或删除历史记录之前，先检查受影响的范围。其他客户端可能也在使用同一个原生服务。
公共帮助站点无需 CodeNomad、其后端或登录即可使用。桌面的 帮助 → CodeNomad 帮助 和命令面板中的打开帮助会以当前界面语言单独打开该站点。更改语言不会翻译已存储的对话。
本地桌面客户端的设置会打开原生偏好设置窗口；浏览器和远程客户端使用内嵌设置。设置 → 提供商之类的路径在两种界面中都指向相同的设置部分。
若要在准备好的主机上运行独立浏览器工作区，请参阅服务器指南，了解以下启动命令及其认证/TLS 要求：
npx @neuralnomads/codenomad --generate-token --launch
选择客户端
| 功能 | 本地桌面 | 直接浏览器或远程服务器窗口 | 远程控制配对设备 |
|---|---|---|---|
| 项目、对话、文件和历史记录 | 后端的文件夹和原生会话 | 所连接服务器的文件夹和会话 | 主机授权的工作区界面 |
| 原生偏好设置和桌面窗口 | 可用 | 浏览器/远程设置保留在客户端内 | 主机专用桌面控件不可用 |
| 会话浏览器预览 | Electron 和 Windows Tauri 使用原生预览；其他 Tauri 平台使用 iframe | 支持时使用 iframe | 主机允许网页预览时使用 iframe（默认） |
| 原生桌面/浏览器自动化 | 所拥有的本地窗口/预览 | 不能代替原生桌面自动化 | 主机专用自动化端点不可用 |
| 认证 | 本地初始化或密码会话 | 服务器密码会话 | 配对设备凭据 |
| PWA 安装 | 使用原生应用或浏览器 | 取决于浏览器；需要安全上下文 | 取决于浏览器；仍需配对 |
具体限制请参阅浏览器预览与 SideCar、远程控制和移动设备/PWA。远程窗口不会将你设备的文件系统变成服务器工作区。
了解状态的归属
| 术语 | 在 CodeNomad 中的含义 |
|---|---|
| 项目标签页 / 工作区 / 实例 | CodeNomad 与显式打开的文件夹之间的连接；多个标签页可以使用共享服务。 |
| 对话 / 会话 | 与其目录关联的原生 OpenCode 历史记录和执行。 |
| 会话族 | 一个对话及其递归子会话；涉及移动、活动、Yolo 和任务控件。 |
| 工作树 | 选择用于浏览或放置会话的、归属已确认的仓库检出目录。浏览它不会移动对话。 |
| Location | OpenCode 按目录划分的原生运行时上下文；关闭项目标签页时 CodeNomad 不会卸载它，其生命周期由 OpenCode 管理。 |
| CodeNomad 后端 | 提供工作区、Git、认证和客户端连接的服务器。其账户和环境决定后端的文件系统访问权限。 |
| 配置 | 服务器配置目录中的 CodeNomad 设置；全局/项目 OpenCode 设置各有其原生作用域。 |
| 窗口 | 拥有各自的标签页、导航、草稿和恢复视图。原生历史记录是共享的，并非为每个窗口复制。 |
| 桌面数据配置文件 | 在设置中选择的原生/客户端存储；不会自动隔离 OpenCode 会话或所有共享配置。 |
工作区根目录限制 CodeNomad 可打开的文件夹，并非智能体沙箱。公开主机或允许广泛的工具访问之前，请阅读安全。
按任务查找
| 任务 | 指南 |
|---|---|
| 安装或提供工作区服务 | 安装、服务器参考、网络与 TLS |
| 跨检出目录和对话工作 | 项目、对话、文件 |
| 查找历史记录或安全清理 | 历史记录 |
| 回答原生问题和权限请求 | 权限 |
| 协调有界任务或每日工作 | 任务 |
| 配置执行和集成 | OpenCode、提供商、集成 |
| 连接另一台设备 | 远程控制、安全、移动设备 |
| 调整工作区 | 设置、快捷键、语音、扩展 |
| 管理原生应用 | 桌面、浏览器预览与 SideCar、更新 |
| 诊断或贡献 | 故障排查、支持与源码构建 |
监控工作而不更改它
状态面板显示活动会话的提供商用量和原生后台 Shell。对话状态和子会话活动标明正在工作、压缩和等待输入的会话。监控后台 Shell 不同于发送输入框 Shell 请求，也不同于使用单独托管的终端 SideCar。
- 打开所选对话 Location 的状态 → 后台 Shell（未选择对话时则为当前工作区）。
- 查看已提供的命令、Shell、目录、状态、PID 和退出码；选择查看输出查看可用的原生输出。
- 若要清除某个 Shell，运行时使用停止并移除，退出后使用移除，并确认目标。
移除正在运行的 Shell 会停止该进程；关闭其输出窗口则不会。刷新/重新连接会读取当前原生状态，而不是重建错过的输出事件。
显示快照会在原生更改、重新连接和可见时按需刷新。它们并非保证可重放的日志。如果结果不确定，请在重试修改操作前刷新权威状态；不要仅因错过通知或事件就再次提交。