mirror of https://github.com/NeuralNomadsAI/CodeNomad.git synced 2026-11-01 03:20:37 +00:00

chore(opencode): recommend OpenCode 2.2.5 (#1222 )

## Summary

- OpenCode **2.2.5** becomes the **recommended** (qualified) runtime.
The **2.2.3 minimum** and the 2.1.0 `@opencode/client`/`plugin`/`schema`
pins stay: neither 2.2.4 nor 2.2.5 changes a contract CodeNomad
consumes.
- `RECOMMENDED_OPENCODE_VERSION` is 2.2.5, and the reviewed-publication
shortcut in `contractProfile` lists 2.2.3 and 2.2.5; other versions,
2.2.4 included, keep negotiating their authenticated schema. The CI
`latest` lane already resolves the latest stable CLI.
- Help (all ten locales), READMEs, `CONTRIBUTING.md`,
`dev-docs/OPENCODE_COMPATIBILITY.md` and the architecture skill state
two separate versions again: minimum 2.2.3 with its reason,
recommendation 2.2.5.

## Contract review (v2.2.3 → v2.2.4 → v2.2.5; 31 + 19 commits)

Reviewed from the exact tags `v2.2.3` (`082ac6281f`), `v2.2.4`
(`45898d0f85`) and `v2.2.5` (`9bbb8ce18c`), the published npm packages,
and an authenticated OpenAPI dump from each official CLI running in its
own sandbox. The [changelog](https://opencode.ai/changelog) has full
notes for 2.2.4 and 2.2.5 (both 30 October); everything below was also
checked against the commit log and source. CodeNomad side: `origin/dev`
`605820669`.

**Headline:** neither release changes a contract CodeNomad consumes.
2.2.4 adds opt-in **artifacts** (seven `/api/experimental/artifacts`
operations, four tools, a plugin hook), **renamable persistent
terminals**, and moves background-job recovery markers from `kv` into a
new **`job` table**. 2.2.5 is a bug-fix release; its one schema change
is that `compaction.buffer` accepts a percentage such as `"20%"`. The
image tool contract adopted in #1209 (`experimental_image_generate`, on
by default) is unchanged through 2.2.5, and still nothing writes
`session_part`.

- **Authenticated OpenAPI:** 134 → **138** → 138 paths, 162 → **169** →
169 operations, schemas 351 → 362 → 363.
- **Added operations (2.2.4):** `GET
/api/experimental/artifacts/providers`, `GET|POST
/api/experimental/artifacts`, `GET|PATCH|DELETE
/api/experimental/artifacts/{artifactID}`, `GET
/api/experimental/artifacts/{artifactID}/view/*`
([#60351](https://github.com/anomalyco/opencode/pull/60351)). None
removed in either release.
- **Changed operations (2.2.4):** `GET /api/event`, where the `types`
filter enum gains `persistent-pty.updated` and `artifact.updated` (94 →
96 types, none removed). `PUT /api/experimental/persistent-pty/{ptyID}`
can also rename (`title`; `null` clears it), `size` becomes optional,
and a 501 `PtyFeatureUnsupportedError` is returned while an older
terminal service can't rename
([#60329](https://github.com/anomalyco/opencode/pull/60329)).
  - **Changed operations (2.2.5):** none.
- **Consumed schemas:** same family selector as the 2.2.3 review, 97
schemas at every version.
- 2.2.3 → 2.2.4: 95 byte-identical. The two that change,
`PersistentPty.Info` (+ `userTitle`, nullable, required) and
`PersistentPty.UpdateInput` (`size` optional, + `title`), are both
additive.
    - 2.2.4 → 2.2.5: all 97 byte-identical.
- `V2EventEncoded`, `Session.*`, `Form.*`, `Permission.*`, `Prompt*`,
`Event.*`, `Location.*`, PTY/Shell are byte-identical from 2.2.3 to
2.2.5.
- **`Config.InfoEncoded`:** 2.2.4 adds `experimental.artifacts`
(boolean, opt-in). 2.2.5 turns `compaction.buffer` into
`Config.Compaction.Percent | integer`
([#60647](https://github.com/anomalyco/opencode/pull/60647)).
`experimental.image_generate`, `experimental.media_blob` and
`experimental.schedules` are unchanged.
- **Admission:** every predicate in `compatibility/negotiate.ts`
(unchanged on origin/dev) holds on 2.2.3, 2.2.4 and 2.2.5.
`contractProfile` lists only `2.2.3` as reviewed, so 2.2.4/2.2.5 are
admitted through authenticated contract recognition.
- **Instance proxy:** the allowlist is unchanged on origin/dev. No added
or changed route is proxied: artifacts and persistent PTYs are outside
it. The proxied `GET /api/config` returns the additive config fields
above.
- **Published declarations** (2.2.3 → 2.2.5):
- **Client:** 185 → **192** → 192 methods. 2.2.4 adds
`experimental.artifacts.{providers,list,create,get,update,delete,view}`,
the artifact and `PersistentPtyUpdated` types, and
`PtyFeatureUnsupportedError`. It removes
`createPtyClient`/`PtyConnectInput` from `@opencode/client/solid/pty`,
which CodeNomad doesn't import. 2.2.5 adds `ConfigCompactionPercent`.
- **Schema:** 2.2.4 adds the `artifact` module and
`PersistentPty.Updated`; 2.2.5 adds `config/compaction` `Percent`.
- **Plugin:** 2.2.4 adds `effect/artifact` and `promise/artifact` and
`ctx.experimental.artifact` (`transform`, `reload`). 2.2.5 has no export
changes.
- **Typecheck:** the server and UI typecheck with **0 errors** against
the 2.2.4 and 2.2.5 client/schema/plugin/effect declarations. The pinned
2.1.0 control is also clean.
- **Host modules:** the bundles' host imports are identical to the 2.2.3
review. A probe plugin in an isolated **2.2.4** and **2.2.5** daemon
resolves every module and binding. `runtime-modules.ts` is unchanged
from v2.2.3 to v2.2.5.
- **Host Effect:** stays **4.0.6** (`bun.lock` sha512 identical;
published `dependencies.effect` 4.0.6).
- **Persistent PTY binary:** the 2.2.4 and 2.2.5 CLIs ship
`@opencode/pty` **0.4.0** (string `opencode-pty 0.4.0` in the Windows
binary; 2.2.3: `0.3.3`). `process-daemon-v0.4.0` adds only terminal
renaming ([#60324](https://github.com/anomalyco/opencode/pull/60324)):
an additive `rename` request and `features: ["rename"]` with an
unchanged `PROTOCOL_VERSION`. CodeNomad only lists persistent PTYs
(worktree deletion guard) and reads `status`/`cwd`.
- **Private native services:** the keys (`LocationServiceMap`, `Form`,
`Permission`, `Location`, `Job`, `Database`, `Session`, `Bus`, `Shell`)
and the members CodeNomad calls are unchanged. The changes are additive:
`Job.cancelSession` (2.2.4), `Permission.allows` (2.2.5; never asks,
used by `edit` to decide whether to quote file lines), and
`Session.remove` now calls `jobs.cancelSession`. The Missions recurrence
clock calls `Job.get/start/cancel`. Its Job metadata carries no
`sessionID`, so deleting a session doesn't cancel it.
- **Storage:** one migration, `20261030054400_job` (2.2.4,
[#60491](https://github.com/anomalyco/opencode/pull/60491)). It creates
`job`, copies every `kv` row `job.background/%` into it and deletes
those `kv` rows. 2.2.5 adds none.
- CodeNomad reads only its own `kv` keys (Missions, pruning receipts and
claims), never `job.background/*`.
- Native migration 2.2.3 → 2.2.4 passes. Every 2.2.4/2.2.5 fixture DB
inspected holds the `job` table, **0** `job.background/` rows and no
leftover `schedule:leader` lease.
- **`session_part`:** still **not written**. `history.ts`/`projector.ts`
are unchanged from v2.2.3 to v2.2.5, the projector still only rewrites
existing part rows, and every inspected 2.2.4/2.2.5 fixture DB has **0**
rows. The forward risk from the 2.2.3 review stands (Recommendations).
- **Behavior changes checked** (plain-language list in [What users will
notice](#what-users-will-notice)):
- **Image tool** (#1209 contract): `image-generate.ts` is unchanged from
v2.2.3 to v2.2.5. 2.2.4 refactors restart recovery into one
`restartMessage` but keeps `metadata.source:
"experimental_image_generate"`, `jobID`, `state`, `path` and the `<image
id state>` notice text. Design companion, activation, content and image
settings pass natively on 2.2.4.
- **Schedules** (2.2.4,
[#60478](https://github.com/anomalyco/opencode/pull/60478), then
`da87c475a7`): the loop now runs in every server process, including
`opencode serve`, and elects a leader through a `kv` lease
`schedule:leader` (claimed at boot, released when there are no active
schedules). Firing stays opt-in (`experimental.schedules === true`).
CodeNomad uses neither OpenCode schedules nor that key; Missions
recurrence uses its own storage and the Job service.
- **Sessions:** deleting a session now cancels its running background
jobs (shell, image, subagent) and drops their markers (2.2.4). That is
the intended upstream cleanup; CodeNomad's session deletions
(blank-session cleanup, temporary workspaces) get it automatically.
- **Events:** `persistent-pty.updated` and `artifact.updated` reach
CodeNomad's shared event relay. The relay routes generically
(`instance-events.ts`), the 2.1.0 client's SSE reader doesn't validate
types, and the UI handles neither type. The native relay suite passes on
2.2.4.
- **Tools** (2.2.5): a model call to `bash` runs as `shell` with shell
permissions, and the result carries a note
([#60687](https://github.com/anomalyco/opencode/pull/60687)). CodeNomad
already groups and renders `bash` and `shell` alike
(`message-part-grouping.ts:48`, `tool-call/utils.ts`). `read`/`edit`
failure texts are richer
([#60688](https://github.com/anomalyco/opencode/pull/60688),
[#60689](https://github.com/anomalyco/opencode/pull/60689)).
- **Compaction** (2.2.5): the prompt is capped at the context window
when a catalog's input limit is larger
([#60660](https://github.com/anomalyco/opencode/pull/60660)), and
`compaction.buffer` may be `"N%"`. CodeNomad never reads or writes
`compaction.buffer`. LiteLLM context errors now trigger compaction
([#60692](https://github.com/anomalyco/opencode/pull/60692)).
- **Reasoning replay** (2.2.5,
[#60498](https://github.com/anomalyco/opencode/pull/60498)): reasoning
is no longer re-sent as plain text after a model switch, and interrupted
or errored reasoning is dropped from the request. This changes provider
requests only; stored transcripts and `Session.Message.*` are
byte-identical.
- **MCP** (2.2.5): stdio messages over 10 MiB no longer disconnect a
server ([#60694](https://github.com/anomalyco/opencode/pull/60694)), and
an idle Location no longer restarts its MCP servers right after shutting
down ([#60668](https://github.com/anomalyco/opencode/pull/60668)).
- **Providers:** a Console-supplied provider can now be overridden by
user, project and remote config (2.2.4). The Claude Agent provider only
replaces Claude Code's `/login` hint with `claude auth login` in its
errors ([#60592](https://github.com/anomalyco/opencode/pull/60592)); the
guided setup
([#60603](https://github.com/anomalyco/opencode/pull/60603)) is OpenCode
Desktop only. The provider ID (`Provider.ID.claudeAgent`) and its use of
Claude Code's own login are unchanged, so CodeNomad's `claude-agent`
quota reader (#1214) is unaffected.
- **Service lifecycle:** the CLI now adds `127.0.0.1,localhost,::1` to
`NO_PROXY`/`no_proxy` for itself and its children
([#60441](https://github.com/anomalyco/opencode/pull/60441)), so
loopback traffic from daemon-hosted code, CodeNomad's plugins included,
bypasses environment proxies. CodeNomad sets no proxy variables.
- **Code Mode, Forms, permission prompts, media blobs:** no source
changes from v2.2.3 to v2.2.5 (`packages/codemode` only bumps its
version). The Code Mode run-to-completion regression passes on 2.2.4: `{
total: 2000, beforeAwait: 1000, count: 1000 }`.
- **`@opencode/ai`:** one `ai` object for Promise and Effect
([#60516](https://github.com/anomalyco/opencode/pull/60516); left out of
the changelog by
[#60631](https://github.com/anomalyco/opencode/pull/60631)). CodeNomad
doesn't import `@opencode/ai`.
- Desktop/TUI-only changes (desktop terminals on persistent PTYs,
base-branch and worktree shortcuts, quote sending, flat inputs, palette
ordering) don't affect CodeNomad. One indirect effect follows.
- **Worktree deletion:** OpenCode Desktop terminals now live as
persistent PTYs that survive restarts
([#60346](https://github.com/anomalyco/opencode/pull/60346)).
CodeNomad's guard (`routes/worktrees.ts`, "Running persistent PTY blocks
deletion: <id>") will therefore refuse more often for users who also
open terminals in OpenCode Desktop. The behavior is correct, but the
message names the PTY ID rather than the terminal's title.

**Verdict:**

- The **2.1.0 client/plugin pins can stay**. Bumping them would bring
only artifacts, PTY renaming and a config type, none of which CodeNomad
consumes.
- The **2.2.3 minimum has no reason to move**. No consumed HTTP, plugin,
private-service or storage contract broke in 2.2.4 or 2.2.5.
- **Recommend 2.2.5.** It is admitted today through contract
recognition. Recommending it is CodeNomad-side bookkeeping:
`RECOMMENDED_OPENCODE_VERSION` (`runtime-support.ts`), the
reviewed-version check in `contractProfile`
(`compatibility/runtime.ts`), the version texts in docs and help, and
CI's qualification target. This is subject to the full native suite on
the exact 2.2.5 CLI, run separately.
- **No CodeNomad bug found** in 2.2.3 → 2.2.5. Risks: the `session_part`
forward risk (unchanged) and the more frequent worktree-deletion refusal
(UX).

**Not verified here:**
- the full native suite on 2.2.5: only a host-module probe ran natively
on 2.2.5, and everything else for 2.2.5 is source and OpenAPI review
(Appendix I);
- the 2.2.4 recurring Missions journey (`test-recurring-simple-native`
ABCDGELFWQN), which was interrupted by a server restart;
- the `kv` → `job` migration with a real pending background marker: only
the empty case ran, and upstream `job.test.ts` covers the copy;
- whether a `bash` call is stored as `bash` or `shell` (source suggests
the model's name is kept; CodeNomad renders both);
- artifacts, Claude Agent and MCP stdio framing at runtime (source
only);
- macOS/Linux.

---

## What users will notice

**OpenCode 2.2.4**
- **Persistent desktop terminals:** OpenCode Desktop terminals belong to
the session, keep their scrollback across server restarts, stay in sync
with the TUI and other windows, and can be renamed. Renamed terminals
keep their names.
- **Artifacts (opt-in):** with `"experimental": { "artifacts": true }`,
agents can publish, update and serve HTML or static artifacts
(`artifact_create`, `artifact_read`, `artifact_update`,
`artifact_delete`) through a built-in local provider, which stores files
under OpenCode's data folder, or a plugin-provided one.
- **Schedules:** enabled schedules also fire under `opencode serve`, and
only once when several OpenCode processes share a database. They stay
off unless `experimental.schedules` is `true`.
- **Claude Agent:** OpenCode Desktop guides installation, `claude auth
login` and connection checking. Error messages now say `claude auth
login` instead of `/login`.
- **Config:** user, project and remote configuration can override
Console-supplied provider names, limits, variants, settings and headers.
- **Networking:** requests to the local OpenCode service no longer go
through `HTTP(S)_PROXY`.
- **Sessions:** deleting a session also stops its running background
work, such as shells, image generations and subagents.
- **Desktop/TUI:** base-branch shortcut, simpler location popover,
faster Markdown streaming and various fixes.

**OpenCode 2.2.5**
- **Compaction:** `"compaction": { "buffer": "20%" }` keeps a share of
each model's context free; token counts still work. Compaction no longer
overfills models whose catalog input limit exceeds their context window,
and LiteLLM context errors trigger compaction instead of stopping.
- **Tools:** a model calling `bash` gets `shell` (with shell
permissions) instead of an error. `read` names the missing folder, and
`edit` shows the closest lines when `oldString` isn't found.
- **Reasoning:** switching models or resuming an interrupted reply no
longer resends reasoning as plain text, which some providers rejected.
- **MCP:** large stdio messages (over 10 MiB) no longer disconnect a
server, and idle locations don't immediately restart their MCP servers.
- **Desktop/TUI:** worktree and base-branch shortcuts, a shell-mode
toggle, sending a single quote from its popup, and MCP servers removed
from the connect menu.

## Follow-ups (outside this PR)

- Hardening for `session_part` (independent of this upgrade; 2.2.5 still
writes no rows): make the direct `session_message.data.content` readers
and the pruning transaction fail safe when `session_part` has rows for
the target messages.
- Optional UX: when the worktree deletion guard finds a running
persistent PTY, name it by `userTitle ?? title` (2.2.4+) and say it may
be an OpenCode Desktop terminal.
- Any future reader of `compaction.buffer` must accept `"N%"` as well as
a token count.

## Isolated Windows qualification

Base: dev `605820669`; Node 25.2.1 (local; CI runs the pinned 24.20.0);
exact official CLI **2.2.5**; locked client/plugin **2.1.0**;
`CODENOMAD_NATIVE_FIXTURE_PARENT` outside the user profile.

- **Native suites on 2.2.5, all passing:** Code Mode jobs, plugin
runtime, automation, session pruning (history, navigation, media blobs,
proxy, session images), Location/worktrees/event relay, permission
receipts, Git init/degraded, Missions (contract, family control, native,
trajectory) and all 11 recurring journeys, sessions (environment, fork,
aside, interrupt, lifecycle, blank cleanup, compaction isolation, prompt
skills), providers (usage, accounts, account selection), service usage,
web search settings, plugin packages, output limit, Promise-tool
failure, subagent depth, temporary workspaces, Design
companion/activation/content, image settings, history migrations from
2.1.2/2.2.3/2.2.4, shared install of the 2.2.3 minimum.
- **Installer suites after the bump:** upgrade (installed `opencode
v2.2.5`) and legacy replacement (target `2.2.5`) install the new
recommendation and pass.
- **Builds and checks after the change:** server build, native plugin
builds and root typecheck clean; server **2,840 passed, 9 skipped, 1
cancelled** (`index.test.ts` shutdown test timed out under full-suite
load; **4/4** alone); runtime-support/transport/update **35/35**;
browser `opencode-setup` **34/34**; ten-locale help **31/31**.

2026-10-31 01:46:05 +01:00

12 KiB

Raw Permalink Blame History

独立服务器

在项目和工具所在位置运行 CodeNomad，然后在本地或远程使用浏览器界面。后端提供文件系统访问、Git 操作、认证和事件交付。OpenCode 共享服务管理对话和执行；它不是浏览器断开后就应停止的子服务器。

同一界面支持多个项目标签页和工作树、对话族和后台活动、有界历史加载、搜索和时间线导航、命令面板和快捷键，以及任务。浏览器和平板访问不会将执行移离主机。

准备主机

安装 Node.js 24 LTS 和 npm；仓库固定构建运行时为 24.20.0。桌面包包含 Node/npm。
将 Git 加入后端进程的 PATH。仅 WSL 内的 Git 不满足 Windows 后端。
安装或选择 OpenCode：必需最低版本为 2.2.3，推荐验证目标为 2.2.5。更新或自定义构建会接受兼容检查，而非已测试版本白名单。参阅 OpenCode 设置。
选择启动服务器的文件夹，或显式传入 --workspace-root。

没有 Git 时，对话仅在显式打开的物理文件夹内可用；Git 和工作树操作失败。安装 Git，更改 PATH 后重启后端。工作区根目录限制打开/浏览，而非智能体执行：参阅安全。

运行或安装

选择一种安装方式。以下首次运行示例使用本地初始化，而非将密码写入 Shell 历史：

使用 npx 运行

npx @neuralnomads/codenomad --generate-token --launch

全局安装

npm install -g @neuralnomads/codenomad
codenomad --generate-token --launch

在项目中安装

npm install @neuralnomads/codenomad
npx codenomad --generate-token --launch

存在项目安装的二进制时，npx codenomad 会使用它。这将软件包安装到该项目；不会使配置或 OpenCode 存储变为项目本地。

在主机打开打印的 Local Connection URL。完成本地初始化，然后保存持久服务器密码。如果尚未配置 HTTPS 信任，该流程也包含仅回环 HTTP 设置选项。
后续启动省略 --generate-token；也可每次启动都提供 CODENOMAD_SERVER_PASSWORD。
使用 codenomad --help 查看已安装 CLI 选项。

命令在前台运行。关闭终端或发送 Ctrl+C 会停止该后端及其远程控制连接。--launch 仅打开浏览器；不会让服务器成为守护进程。需要无人值守可用性时，在操作系统进程/服务管理器下运行同一命令，并显式指定配置、工作目录、环境和重启策略。不要将秘密写入服务日志或公开 unit 文件。

关闭浏览器不会停止单独运行的独立后端。关闭项目标签页会在 CodeNomad 中关闭该项目，CodeNomad 不再跟踪该连接。OpenCode Location 不会卸载，会话继续运行；重新打开项目即可再次找到。关闭后端同样让 OpenCode 服务继续运行。依赖后端的功能会在 CodeNomad 返回前不可用；独立的原生调度生命周期参阅任务。

地址与端口

启动时打印 Local Connection URL，可用时还打印 Remote Connection URL，适用时另有 Other Accessible URLs。请使用打印的协议和端口，不要猜地址。回环 URL 仅在该机器可达；打印的局域网地址仍需要路由和防火墙访问。

HTTPS 首选端口 9898，HTTP 首选 9899。没有端口覆盖时，首选端口被占用会回退到操作系统分配端口。显式非零端口不回退；0 请求操作系统分配。端口接受 0 至 65535 的整数。

后端还可能在随机的 127.0.0.1 端口上打开一个不公布、需认证的 HTTP 监听器，供其自身的 OpenCode 插件（如任务）使用。它不会被打印，也不是客户端地址。

监听器暴露、证书、VPN/SSH 和反向代理请参阅直接远程访问。无需入站端口的访问请使用远程控制。

公共 CLI 参考

标志覆盖对应环境变量。带值标志使用所示参数；开关不带值。HTTPS/HTTP 值不区分大小写，将 1、true、yes、y 和 on 识别为启用；为清晰起见请显式使用 true/false。界面自动更新识别 1、true 和 yes。

严格布尔环境变量（CLI_UNRESTRICTED_ROOT、CLI_UI_NO_UPDATE、CLI_LAUNCH、CODENOMAD_GENERATE_TOKEN 和 CODENOMAD_SKIP_AUTH）在值为 1、true、yes 或 on 时启用相应开关，忽略大小写及两端空白。0、false、no、off、空值、仅含空白的值或未设置的变量均让开关保持关闭。任何其他值都会阻止服务器启动，即使指定了对应的 CLI 标志。CLI 标志可覆盖有效的关闭值并启用开关；否则使用下列 false 默认值。

标志	环境变量	默认值与影响
`-h, --help`	—	打印帮助并退出。
`-v, --version`	—	打印已安装软件包版本并退出。
`--host <host>`	`CLI_HOST`	`127.0.0.1`；`localhost` 规范化为 IPv4 回环。拒绝 IPv6 区域标识符。参阅绑定矩阵。
`--https <enabled>`	`CLI_HTTPS`	`true`；HTTPS 监听器。
`--http <enabled>`	`CLI_HTTP`	`false`；HTTP 监听器。至少启用一个监听器。
`--https-port <number>`	`CLI_HTTPS_PORT`	首选 `9898`；`0` 自动。
`--http-port <number>`	`CLI_HTTP_PORT`	首选 `9899`；`0` 自动。
`--tls-key <path>`	`CLI_TLS_KEY`	未设置；PEM 私钥，要求 `--tls-cert`。
`--tls-cert <path>`	`CLI_TLS_CERT`	未设置；PEM 证书，要求 `--tls-key`。
`--tls-ca <path>`	`CLI_TLS_CA`	未设置；所提供证书的可选 PEM CA 链。
`--tlsSANs <list>`	`CLI_TLS_SANS`	未设置；为生成证书添加的逗号分隔 DNS 名/IP。
`--workspace-root <path>`	`CLI_WORKSPACE_ROOT`	进程工作目录；打开工作区的根目录。
`--unrestricted-root`	`CLI_UNRESTRICTED_ROOT`	`false`；允许浏览整个文件系统。不是智能体沙箱设置。
`--config <path>`	`CLI_CONFIG`	解析后的活动默认值：`~/.config/codenomad/config.yaml`。接受目录或 YAML 文件以显式指定位置。
`--log-level <level>`	`CLI_LOG_LEVEL`	`info`；文档级别：`trace`、`debug`、`info`、`warn`、`error`。
`--log-destination <path>`	`CLI_LOG_DESTINATION`	`stdout`；否则写入指定文件。
`--username <username>`	`CODENOMAD_SERVER_USERNAME`	`codenomad`；运行时认证用户名。没有运行时密码覆盖时，已存储认证文件保留其用户名。
`--password <password>`	`CODENOMAD_SERVER_PASSWORD`	未设置；仅运行时密码，优先于受管理认证文件。
`--auth-cookie-name <name>`	`CODENOMAD_AUTH_COOKIE_NAME`	`codenomad_session`；字母、数字、`_` 和 `-` 之外的字符变为 `_`。
`--generate-token`	`CODENOMAD_GENERATE_TOKEN`	`false`；打印一次性、有效 60 秒的本地初始化令牌。
`--dangerously-skip-auth`	`CODENOMAD_SKIP_AUTH`	`false`；禁用直接监听器认证。危险：参阅安全。远程控制仍要求设备配对。
`--ui-dir <path>`	`CLI_UI_DIR`	软件包的 `public` 目录；显式覆盖时提供该界面，而非解析远程界面。
`--ui-dev-server <url>`	`CLI_UI_DEV_SERVER`	未设置；通过 HTTP 监听器代理界面。开发时使用 `--https=false --http=true`；HTTPS 监听器不代理开发界面。
`--ui-no-update`	`CLI_UI_NO_UPDATE`	`false`；覆盖自动更新，使用可用的缓存/随附界面。
`--ui-auto-update <enabled>`	`CLI_UI_AUTO_UPDATE`	`true`；启动时检查兼容远程界面。
`--ui-manifest-url <url>`	`CLI_UI_MANIFEST_URL`	`https://ui.codenomad.neuralnomads.ai/version.json`；远程界面清单。
`--launch`	`CLI_LAUNCH`	`false`；启动后在浏览器打开本地界面。
`--upgrade [version]`	—	默认不升级。请求时，全局安装 `@neuralnomads/codenomad@latest` 或所提供版本，然后退出。

公共参考列出面向用户的选项；桌面宿主管理自身私有启动协调。

其他部署环境

变量	默认值与范围
`CODENOMAD_GITHUB_REPO`	`NeuralNomadsAI/CodeNomad`；查询发行版本的仓库。
`CODENOMAD_REMOTE_CONTROL_API`	未设置：托管 OpenTunnel API。自托管中继部署时设置 API 来源。
`NODE_EXTRA_CA_CERTS`	Node 可选额外 CA 文件；启动缺失的 OpenCode 守护进程时与允许的启动环境一起传递。不改变已运行守护进程。

提供商专用用量凭据见提供商。桌面数据配置文件选择见桌面，不受发布通道控制。

配置与存储归属

以下默认路径使用后端用户主目录。显式 --config 目录改变配置根目录；YAML 文件名选择该文件及同级状态/存储。每个部署请有意识地使用一个配置身份，并用操作系统权限保护整个目录。

所有者/数据	默认位置或规则
稳定 CodeNomad 偏好	`~/.config/codenomad/config.yaml`
可变 CodeNomad 状态	`~/.config/codenomad/state.yaml`
CodeNomad 实例元数据	`~/.config/codenomad/instances/`
密码哈希	活动 YAML 配置旁的 `auth.json`；应用管理。
生成的 TLS 证书和私钥	配置根目录下的 `tls/`。
远程控制路由、启用选择和设备哈希	配置根目录下的 `remote-control-devices.json`。
临时工作区注册表和文件夹	该根目录下的 `temporary-workspaces.json` 和 `temporary-workspaces/`。
已安装面板扩展和权限回执	该根目录下的 `panel-extensions/` 和 `permission-receipts/`。
下载界面缓存	`~/.config/codenomad/ui/`；即使用自定义 `--config`，CLI 界面解析器仍使用此基于主目录的缓存。
OpenCode 对话、消息、服务注册和提供商连接	执行主机上 OpenCode 自身的全局存储，而非 CodeNomad 实例目录。
桌面恢复状态	默认 `~/.codenomad/client-state/v2/`；配置文件/窗口范围参阅桌面。

CodeNomad 连接现有共享守护进程，缺失时启动。启动环境仅影响新启动的守护进程。另行配置的完整会话环境会在每条提示词、自定义命令或会话 Shell 请求前应用，而非仅查看或编辑偏好时。参阅 OpenCode 设置。

事件与重新连接

后端消费共享原生 OpenCode 事件流，使用服务器发送事件向浏览器客户端复用传输工作区和 CodeNomad 事件。交付是实时、易失的：不保证事件重放。

重新连接后，界面重新获取权威会话和待处理请求状态；文件/配置失效也触发新读取。重新连接不意味着允许重复回复丢失的发送、删除、回答或其他修改操作。请先检查结果状态。恢复不完整时保留已知待处理请求和草稿；参阅权限和故障排查。

预览包与维护

显式试用预览 CLI 软件包：

npx @neuralnomads/codenomad-dev --generate-token --launch

需要隔离 CodeNomad 设置时，请有意使用独立配置；选择软件包不会隔离共享 OpenCode 存储。设置 → 信息 → 更新 → 更新通道控制提供的版本，而非后端数据身份或已安装软件包。

codenomad --upgrade 使用检测到的 npm/pnpm/bun 管理器更新全局稳定 CLI 包（未检测到时使用 npm）。不会重启运行中的服务器，也不会更新 OpenCode。对于项目本地或预览安装，请显式更新对应 npm 软件包。更新后有意识地重启受管理 CodeNomad 进程；重新检查打印地址。

桌面维护参阅更新，构建命令参阅从源码构建，提供商计划用量参阅提供商。

12 KiB Raw Permalink Blame History Unescape Escape