跳至指南

故障排除

如果 onemind 未能按预期运行，请先运行 onemind version 确认安装，然后查找以下匹配条目。

找不到 onemind

  • macOS/Linux：确认 ~/.local/bin 已加入 PATH，然后打开新终端。
  • 再次运行安装程序，以修复二进制文件和服务注册。

浏览器授权已过期或被拒绝

按 Escape，再次选择 登录，然后在浏览器中批准新请求。被拒绝或过期的请求无法重复使用。

onemind 无法连接服务器

运行 onemind session status 查看当前使用的 API 地址。如需更改，请在终端运行 onemind server https://your-server。只接受 https:// 地址；纯 http:// 仅允许用于本地回环地址。更改服务器后，之前的凭据会被删除；运行 onemind 并选择 登录 以连接新服务器。

同步提示未连接本地项目

当没有活跃 binding 时，onemind sync 会打印以下消息之一：

  • "Sync has not started. Detect an AI tool with 'onemind project TOOL'" — 运行 onemind project TOOL /path/to/repo 检测代码仓库，然后在同步设置中将其绑定到普通 Project，再次运行 onemind sync。
  • "Sync setup is saved, but local access is blocked" — 路径已存在于同步设置中，但进程无法读写该目录。授予所需文件系统权限，然后再次运行 onemind sync。
  • "Sync setup is saved, but the local target is unavailable" — 绑定路径不存在或 AI 工具未运行。启动或修复 AI 工具，按需恢复路径，然后再次运行 onemind sync。
  • "Select this device, target, and Project at …" — 该设备或目标尚未在同步设置中启用。打开同步设置，为此设备和目标启用同步，然后再次运行 onemind sync。

同步拒绝 AGENTS.md

管理标记损坏或存在歧义时，onemind 会停止。请恢复一对有效标记，运行 onemind mind restore pre-onemind --yes 回到 onemind 接管前的 agent 提示词，或手动将 .one-mind/AGENTS.md.backup 复制回正在使用的指令文件；手工编辑时务必保留管理区块之外的所有内容。

撤销首次 Mind 同步

首次 Mind 同步之后，恢复的含义是回到 onemind 接管前的状态——指令文件中原先的本地 agent 提示词——而不是恢复某个 Matrix Mind 版本。

onemind mind backups --path /path/to/destination
onemind mind restore pre-onemind --path /path/to/destination --file AGENTS.md --yes

对于全局工具主目录，将 --path 设为该工具根目录（例如 ~/.codex 且 --file AGENTS.md，或 ~/.claude 且 --file CLAUDE.md）。直接修改 ~/.codex 或 ~/.claude 是最后手段的恢复步骤；请始终从备份副本开始操作，并保留管理区块之外的所有内容。

后台服务未运行

运行 onemind service status。如果失败，请尝试 onemind service install，然后再次检查状态。在 Linux 上，请确保用户 systemd 会话和 Secret Service/keyring 可用。

安全凭据存储不可用

onemind 不会降级使用明文凭据。请启动或解锁操作系统凭据服务，然后重新打开 CLI 并再次登录。

在安全存储中未找到会话

如果 CLI 报告"OneMind session not found in secure storage"，说明存储的凭据已被删除或从未写入。运行 onemind 并选择 登录 以创建新会话。

OneMind 版本降级被拒绝

如果同步因"refusing OneMind version regression from vN to vN"而停止，说明云端包含一个由旧版 CLI 写入的管理区块，而当前指令文件的所有者是更新的 CLI 版本。这通常意味着同步运行后 CLI 被降级。请使用 CLI 快速开始 中的官方安装程序重新安装当前版本，然后再次运行 onemind sync。

提案失败

onemind propose 可能因以下消息之一而失败：

  • "choose an exact Project target in OneMind before proposing" — 当前目录没有活跃的 Project binding。运行 onemind project TOOL /path/to/repo 并完成同步设置后再提案。
  • "proposal is queued locally; exact Project upload is not active" — 提案已在本地保存，但由于 Project binding 未完全激活，上传被阻止。完成同步设置，然后运行 onemind sync 冲刷已排队的提案。

Matrix 面板中的权限请求显示为已过期

工具请求若未及时回应则会过期。如果任务详情面板对某个请求显示已过期或已取消，说明工具已按拒绝处理，其运行可能在没有该操作的情况下继续进行。请先查看运行状态和输出，再决定是否发送后续消息；如果工具仍需要权限，会发起新的请求。

同步显示"需要恢复"或"确认超时"

在同步活动中打开同步详情，查看状态下方的说明。

需要恢复：同步无法安全完成确认。请打开目标设备并按照屏幕提示执行恢复步骤。该设备必须在线且已登录。

已回滚：设备已恢复到之前的文件，无需进一步操作，除非仍需完成此次同步。

确认超时：设备未在规定时间内确认结果。请检查目标设备是否在线、已登录，以及后台服务是否正在运行，然后在同步详情中查看其恢复状态。

Matrix 任务持续等待设备

分配给原生 AI 工具的任务在被分配工具的设备尚未认领运行时，会显示"正在等待 [device] 接取"。如果状态显示该设备处于离线状态，请将任务重新分配到其他设备或工具以继续执行。重新分配步骤请参见 Matrix 对话。

任务对话已达上限

当对话无法继续时，会显示以下两条消息之一：

  • 文件或上下文达到上限（任务对话）："此任务对话已达文件或上下文上限。"请从当前草稿中删除文件或缩短消息，之前的记录将保留。
  • 上下文窗口已满（onemind 智能体）："上下文已用至 100%，onemind 无法回复。请开始新对话以继续。"请开启新的 onemind 智能体对话以继续。

详情请参见 Matrix 对话和 onemind 智能体。

Mind 处于只读状态

如果 Mind 的编辑和提交操作被禁用，且面板显示 Mind 变更暂时处于只读状态，说明团队的活跃成员数量超出了套餐的席位上限。移除成员以将数量降至上限以内、为当前成员数量增加席位，或升级套餐后，写权限将会恢复。席位和套餐选项请参见套餐与账单。

付款仍在确认中

完成结账后，产品会显示确认中状态，等待服务器收到 Paddle 的已验证确认。通常在几秒内即可完成。如果确认中状态持续数分钟，请刷新页面或重新登录。如果套餐未能激活，请通过支持联系客服。账单详情请参见套餐与账单。