CodeNomad 帮助

认证与安全

访问 CodeNomad 可以通过 OpenCode 在后端主机上执行工作。请将服务器密码、浏览器会话和配对设备视为强权限凭据。CodeNomad 不是多租户执行沙箱。

选择服务器认证方式

方式 生命周期与范围
--password 或 CODENOMAD_SERVER_PASSWORD 该后端进程的运行时覆盖值。每次启动需重新提供；不持久保存。覆盖受管理密码文件。
在设置中设定的密码 将加盐 scrypt 哈希持久保存在活动 YAML 配置旁的 auth.json 中。后续启动无运行时覆盖时使用。
--generate-token 启用本地一次性初始化；打印的令牌有效 60 秒。它不是可复用 API 令牌或远程控制链接。
远程控制配对 独立的设备 cookie 认证，从主机管理；参阅远程控制。

默认用户名为 codenomad。已存储认证文件保留其用户名；仅更改 --username 不会重命名该存储身份。未配置密码、初始化模式或显式跳过认证时，服务器拒绝启动。

优先使用受保护的环境/服务秘密，而非将密码嵌入命令参数或 Shell 历史。能够检查进程环境或配置目录的人仍可能攻破部署。

初始化持久密码

  1. 在本地启动，不提供运行时密码覆盖。若想先通过回环地址初始化而不配置证书，使用 codenomad --host 127.0.0.1 --https=false --http=true --generate-token --launch。
  2. 在后端机器上，打开打印的 Local Connection URL 下的 /auth/token，提交 CODENOMAD_BOOTSTRAP_TOKEN: 后打印的值。不要共享该输出。
  3. 打开设置 → 远程访问 → 直接访问（局域网，高级） → 服务器密码。
  4. 选择设置密码，填写至少八个字符的新密码和确认密码，然后选择保存密码。
  5. 下次启动省略 --generate-token，直接连接使用保存的密码。启用远程访问前配置可信 HTTPS；回环 HTTP 设置命令不是远程部署命令。

初始化仅接受来自主机自身回环监听器的请求，不接受局域网客户端或远程控制入口。设置时保持默认回环绑定。令牌过期或已使用时，需要重新以初始化方式启动。如果已存在持久密码，初始化会话可改为选择修改密码。

auth.json 由应用管理；不要手动编辑哈希或公开文件。密码来自 CLI/环境时，设置拒绝替换：请移除覆盖后重启以使用现有受管理密码，或用本地初始化设置密码。认证文件不可读或不可写时，需要修复操作系统权限/路径，而非禁用认证。

浏览器会话与撤销

直接登录会创建不透明的后端内存会话和 codenomad_session cookie（或配置的 cookie 名）。cookie 为 HttpOnly、SameSite=Lax，作用域为 /，通过 HTTPS 签发时标记为 Secure。它们是浏览器会话 cookie；后端重启使内存会话失效。收到提示时请就地重新认证，而非重发失败的修改操作。

更改密码会改变后续凭据检查；不会使已签发的直接会话或远程控制设备失效。怀疑被入侵时：

  1. 限制网络暴露并在主机设置新密码，或更改运行时秘密并重启。
  2. 重启后端，使现有直接会话失效。
  3. 在远程控制 → 已配对设备下单独撤销未知设备。需要立即切断整条访问路径时，停止远程控制。
  4. 检查受影响文件、提供商账户和原生 OpenCode 活动。停止访问不会回滚已接纳的工作。

远程控制独立的 30 天不活动过期和五分钟配对链接请参阅远程控制。更改密码不等于撤销设备，停止隧道不等于删除设备。

保护传输和监听器暴露

直接远程访问请使用可信 HTTPS。明文 HTTP 会向任何能观察该网络链路的人暴露密码、会话 cookie 和工作内容。TLS 在反向代理终止时，请将后端链路保持在回环或其他受保护网络中；代理 TLS 不会加密暴露的上游 HTTP 连接。

--dangerously-skip-auth / CODENOMAD_SKIP_AUTH 禁用 CodeNomad 直接监听器登录，并将请求视为已认证。它不会让服务器变得可以安全公开。监听器可达且没有强制访问边界时，任何能到达的人都会获得访问权限；仅有 VPN 连接不能区分可信和不可信 VPN 用户。除非已独立设计并验证每条访问路径，否则保持认证启用。即使使用此标志，远程控制仍要求配对设备。

请检查绑定矩阵和 TLS 流程，尤其是独立 HTTP-only 模式：它遵循 --host，可能将明文暴露到回环之外。切勿通过禁用验证解决证书错误。

CODENOMAD_SKIP_AUTH=false 会保持认证启用，除非指定了 --dangerously-skip-auth。1、true、yes 或 on 会启用认证绕过，忽略大小写及两端空白；0、false、no、off、空值、仅含空白的值或未设置的变量均让绕过保持关闭。任何其他值都会阻止服务器启动，即使指定了 CLI 标志。该标志可覆盖有效的关闭值；参阅 CLI 参考。

理解主机边界

--workspace-root 限制可打开的工作区，--unrestricted-root 放宽浏览。两者都不是操作系统隔离区、容器、文件系统沙箱，也不限制已授权原生工具能做什么。智能体、Shell 命令、插件和 MCP 工具使用执行主机权限及各自配置的凭据操作。

SideCar 是可信的附加组件。CodeNomad 不会向 SideCar 服务提供自身的登录 cookie 和配对设备 cookie，但 SideCar 页面与 CodeNomad 在同一源中加载，其脚本可以凭借你的登录会话执行操作。只注册你像信任 CodeNomad 本身一样信任的服务。

需要真正隔离时，使用操作系统账户、容器/虚拟机和上游权限配置。不要仅因预期设备只看得到一个标签页就授予访问。服务器配置和共享 OpenCode 服务可能影响其他对话/项目；各自边界请参阅 OpenCode 设置、权限和扩展。

保持凭据和诊断信息私密

OpenCode 管理提供商连接及其全局对话存储。对于受支持用量集成，CodeNomad 在服务器端读取连接元数据和所选凭据；浏览器 API 不返回提供商秘密值。外部 OAuth 登录刷新归其所属方管理；CodeNomad 不交换这些刷新令牌。参阅提供商。

材料 处理方式
密码、初始化令牌、配对链接、cookie 切勿粘贴到问题报告、截图、Shell 记录或共享日志。
auth.json、TLS 私钥、隧道身份、配置秘密 使用操作系统权限和加密备份保护；不要为支持上传完整目录。
对话文本、附件、工作区路径和远程地址 共享前检查/脱敏；可能识别人员、项目或基础设施。
提供商密钥和语音凭据 仅输入到预期设置/凭据所属方；检查哪个提供商收到数据。参阅语音。
debug/trace 日志和网络抓包 仅收集所需内容，在本地检查，报告前脱敏。不要假定每个下游工具输出都不含秘密。

设置 → 信息 → 报告错误会准备有界诊断信息，不预填监听器、地址、路径、凭据或对话内容。提交前请检查自行添加的内容。参阅支持。