故障排查

本页按症状组织。有两件事能解决出乎意料多的问题，先试它们：重启 ORG-2，因为有好几个子系统只在启动时探测你的环境；以及打开 ~/.orgii/logs/orgii.log，看看真正被抛出的是哪条错误。

安装与启动

macOS 拒绝打开应用

官方 macOS 版本是 Apple Silicon 构建，用 Developer ID 证书签名并已公证，Gatekeeper 应当直接放行 .dmg。如果你仍然看到「无法打开，因为无法验证开发者」，那要么这份安装包不是从官方发布页下载的，要么应用是你自己构建的——本地构建没有签名，会被隔离，此时在访达里右键点击，选择打开，确认一次即可。

macOS 没有 Intel（x86_64）构建。在 Intel Mac 上请从源码构建。

Windows 弹出 SmartScreen 警告

Windows 安装程序和 MSI 通过 Azure Trusted Signing 签名。如果 SmartScreen 仍然显示「Windows 已保护你的电脑」，先确认文件来自官方发布页，然后选择更多信息 → 仍要运行。绝不要为来自镜像站或聊天消息的二进制文件跳过它。

没有 Linux 下载

发布流程只构建 macOS（Apple Silicon）和 Windows（x64）——没有官方发布的 AppImage、.deb 或 .rpm。在 Linux 上请从源码构建，需要 Node.js 20 及以上、pnpm 9.15、Rust 1.85.0 及以上、Python 3，以及你所用发行版的 Tauri 前置依赖：

pnpm install
pnpm run download:sidecars
pnpm run tauri:dev

智能体与 CLI

智能体起不来，或者某个 CLI 显示「未安装」

设置 → 依赖项和设置 → CLI Agent 会逐个工具显示已安装或未找到，并附上检测到的版本。你明明装了、却被识别成缺失的 CLI，几乎总是 PATH 的问题：在 macOS 上，从程序坞或访达启动的应用拿到的是一份被削过的 PATH，通过 Homebrew、nvm、fnm、pipx、uv 和 cargo 装的东西全都看不见。ORG-2 在启动时会绕开这一点：向你的登录 shell 问一次真实的 PATH（$SHELL -i -l -c 'echo $PATH'，然后是 $SHELL -l -c 'echo $PATH'），再把 /opt/homebrew/bin、/usr/local/bin、~/.local/bin 和 ~/.cargo/bin 中存在的目录追加进去。这次探测五秒后超时，所以一个会卡住的 rc 文件，最后只会给你留下这几个目录。

1. 在新开的终端里确认这个 CLI 能被解析到（which claude、which codex）。
2. 如果能，就把二进制文件或它的软链接放进上面任意一个目录，或者把 PATH 的 export 挪进 ~/.zshrc。
3. 重启 ORG-2。探测缓存 ~/.orgii/dependencies.json 会在启动时清空，所以重启会强制重新扫描；设置 → 依赖项里也有一个刷新操作。

如果识别到的是错误的版本，把 PATH 上那份陈旧的删掉。

用不了 Browser Use 或 Computer Use

两者都需要可选的原生 sidecar，而这些 sidecar 是有意不打包进已公证应用、也从不在启动时下载的：agent-browser 负责浏览器自动化（macOS、Linux、Windows），peekaboo 负责桌面自动化（仅 macOS）。请显式安装：

• 打包版应用： 设置 → 内置工具 → Computer Use → Sidecar 下载 → 下载。二进制文件会落在 ~/.orgii/bin/；刷新状态会重新检查，最近错误会说明失败原因。
• 从源码： 执行 pnpm run download:sidecars，它会装到 src-tauri/bin。缺失的 sidecar 在构建时只会得到一个占位文件，所以在你把它下载下来之前，对应能力一直是关着的。

如果想改用自己维护的构建，请设置 Agent Browser CLI 路径。Computer Use 还额外需要 macOS 的辅助功能权限——设置 → Computer Use 会显示已授权 / 未授权，并提供一个重新检查的操作。

密钥与认证

密钥显示「密钥无效」或「已暂停 - API Key 验证失败」

打开设置 → 模型 & Keys，用自动检测 / 验证重新校验一次。如果服务商已经吊销或轮换了这个密钥，编辑表单会有意不让你就地改掉——请删除该账号并重新添加。

某个 CLI 智能体的订阅登录不好使了

订阅登录（Claude Code、Codex/ChatGPT、Gemini、Cursor）把 OAuth token 存在本地，并且会过期。请在设置 → 模型 & Keys 里重新走一遍登录流程，或者使用该智能体的检测操作——Codex 读取 ~/.codex/auth.json 和 OPENAI_API_KEY，Gemini 读取 ~/.gemini/oauth_creds.json 和 GEMINI_API_KEY。检测的前提是这个 CLI 已经装好，并且至少登录过一次。

你被限流了

ORG-2 会自动重试，期间显示 API 频率受限，正在重试... 以及尝试次数，并提示你在它退避时先切到别的窗口。持续被限流通常意味着套餐额度已经耗尽——如果服务商上报这些数据，密钥上的配额信息会显示套餐、用量、上限和重置日期。

代理、VPN 与企业 TLS

设置 → 设备 & 网络（Device & Network）会显示检测到的地区、按域名统计的请求、VPN 状态，以及 Git Proxy。当 git 在企业代理后面失败时，在这里设置 HTTP Proxy / HTTPS Proxy——保存时，当前来自环境变量的代理会被写进你的全局 git 配置。如果模型请求在做 TLS 拦截的网络里一直挂着，把 HTTP 版本从自动（推荐）改成仅 HTTP/1.1。

登录 ORG-2 Cloud

浏览器已经登录成功，桌面端却一直没反应

Cloud 登录是一座桥：桌面端带着 return_to 打开托管的登录页，该页面发一封魔法链接邮件，链接落到 /auth/callback，由浏览器端校验 code 并跳转到 /auth/desktop，会话 token 只放在 URL 的 fragment 里，再由这个页面交回应用。如果你被撂在「Signed in」页面上：

1. 点 Open ORG2。这个按钮就是为那些会拦截自动跳转到自定义 URL scheme 的浏览器准备的。
2. 确认 ORG-2 正在运行，而且是安装过的、不只是构建出来的——应用会向操作系统注册 orgii:// scheme，未注册的 scheme 点了不会有任何反应。
3. 用发起登录的那个浏览器、在同一台机器上打开魔法链接：code 交换在客户端完成，需要那个浏览器存下的 PKCE verifier，而回调也只能到达本机进程。

「No session found in this link」表示 fragment 被剥掉了；回到桌面端重新开始。隔离的本地实例用 orgii-instance2:// 到 orgii-instance99://，而不是普通的 orgii://，而且只接受完全匹配的回调——其他一律直接失败，所以 return_to 里写错一个字，症状恰好就是这个。

会话

会话看起来卡住了

用会话侧边栏里的停止 Agent 进程，然后读一读轨迹面板里最后几条事件——看起来冻住的会话，往往是在等一个权限请求，或者一个已经滚出视野的询问用户提问。

shell 命令挂住了

ORG-2 不会杀掉长时间运行的命令。超过 Command Timeout 秒（按智能体配置，1–600）之后，它会把命令转到后台并让它继续跑，并期望智能体用 run_shell 配合 cat/tail 去查看进展，或者把它杀掉。你也可以用 shell 工具调用上的停止控件自己停掉它。

CPU 或内存占用很高

设置 → 设备 & 网络 → 性能监控会把占用拆成后端 RSS、WebView 渲染进程、GPU 与网络辅助进程，以及终端/工具辅助进程，并列出实时的子进程和 30 分钟的 RAM 历史。工具辅助进程占大头，通常说明某个智能体留下了还在后台跑的命令。

很长的会话变慢，或者丢掉了早先的上下文

开启上下文压缩后，较早的消息会被摘要，最近的消息保持原文，聊天区会先提示即将自动总结上下文。调整触发比率、保留比率和摘要模型。关掉它，ORG-2 就改为静默截断——所谓「智能体忘事了」，通常说的就是这个。

回放

回放是空的，或者缺事件

• 「暂无事件」 表示这个会话没有记录到任何活动——回放渲染的就是事件日志。
• 旧会话会丢事件。 清理任务会删掉超过 30 天的 sessions 和 events 行，浏览器截图则超过 7 天就删。
• 共享出来的会话只显示元数据。 请让所有者把它的访问级别调到完整 replay（Full replay）。
• 筛选器把事件藏起来了。 在断定数据丢失之前，先把回放的事件筛选器重置为所有事件。

Git 与 worktree

push、pull 或 fetch 报认证错误

ORG-2 会弹出需要 GitHub 身份验证对话框，并提供就地恢复的几条路：从 macOS 钥匙串或 git 凭据助手加载，或者直接粘贴用户名和个人访问令牌。要一劳永逸，请用设置 → 集成 → Git——连接 GitHub、保存一个 token，或者用从系统检测（gh CLI、SSH 密钥、凭据助手）。token 过期会提示「Your GitHub token has expired」，也在同一个地方重新连接。

某个分支「已在 worktree 中检出」

会话可以跑在隔离的 git worktree 里，而 git 不允许同一个分支被检出两次。分支选择器会把这些分支标为使用中，并显示对应的 worktree 路径。切到那个 worktree，或者用移除 Worktree——它会删掉检出目录，但保留分支和提交。

仓库状态是脏的

如果某个会话留下了没提交的改动，源代码管理面板提供暂存和 View Stash，让你不丢任何东西也能回到干净的工作树。要把一个会话的成果直接扔掉，用丢弃 Worktree——这个操作无法撤销。会话已经不存在的 worktree 会被自动清除。

日志、应用数据与诊断

ORG-2 写下的一切都在 ~/.orgii/ 底下。

轮转出来的日志超过 30 天会被清理。设置 → 存储里有数据目录和日志文件，并配了打开文件夹；设置 → 设备 & 网络 → 磁盘使用会按类别拆解这个目录，并支持逐类清理。

想要更细的信息，就在启动 ORG-2 之前设好 RUST_LOG；它会覆盖默认过滤器（info，其中 key_vault 和 agent_core 为 debug）。panic 由专门的 hook 捕获，所以崩溃会留下一个带 backtrace 的 === PANIC === 块。

怎样提一份靠谱的 bug 报告

到 github.com/org2AI/ORG2/issues 开一个 issue，写上你的 ORG-2 版本（设置 → 应用更新 → 当前版本）、操作系统和架构，你装的是发布版还是自己从源码构建的，精确的复现步骤，orgii.log 和 frontend.log 中故障前后的那一段，以及任何和界面有关的问题的截图。先把密钥和 token 涂掉。安全漏洞不要开公开 issue——按 SECURITY.md 走。

获取帮助

• Discord： discord.gg/tvWgAqhCzs —— #how-to-use-org2 和 #faq 讨论安装与使用，#feedback 提想法和 bug。
• GitHub issues： github.com/org2AI/ORG2/issues 提可复现的 bug 和功能需求。

下一步

• 安装 —— 平台要求与首次启动。
• API 密钥 —— 添加、验证和轮换服务商密钥。
• 会话 —— 会话如何运行、暂停和恢复。
• 回放 —— 读懂一条录下来的轨迹。