--- title: 问题排查 description: 真正会出问题的那些事——状态点不动、Agent 起不来、重启之后会话不见了、一台机器不应答了、手机连不上——每一条都给一个去看而不是去猜的办法。 x-i18n: source_path: troubleshooting.mdx source_hash: 0575b9d430205819ca0b6e476e68f4e72a6e679b9f887409d04ea5fc4f794366 generated_at: 2026-10-10 --- 几乎所有看起来像 Fyolo bug 的东西，都是下面这些情况之一，而每一条都有一个去查而不是去猜的 办法。在提任何问题之前，先从这里开始。 ## 先跑这三条 在任何机器、任何状态下，这三条能回答掉大部分问题： ```bash fyolod status # 这里装了什么，有没有 daemon 在应答？ fyolod list # 它手上有哪些会话？ fyolod logs -n 200 # 没人看着的时候发生了什么 ``` 尤其是 `fyolod status`，它终结了相当一部分「它坏了」的报告：它会说装的是哪个二进制、哪个 版本，以及 socket 上到底有没有东西在听。想问另一台机器，`fyolod list --host ` 会通过 你自己的 SSH 配置去查那台机器上的 daemon。 ## 状态点从来不变 侧栏的[状态点](/zh-CN/docs/sidebar#status)来自装进每个 Agent 自己配置里的 hooks，而它们是 **按设备**安装的。一台在你打开这个功能之前就设置好的机器上的 Agent 没有 hooks，所以它什么 也不汇报，Fyolo 只能退回去读屏幕。 打开**设置 ▸ 远程主机**，选中那台机器，进入它的 **Agent** 页面，按**重新安装 Hooks 和技能**。 本机上对应的修法是**设置 ▸ Agent** 里的**安装到本机**。参见 [状态 hooks 与会话控制](/zh-CN/docs/session-control)。 ## Agent 停在「要信任这些 hooks 吗？」的提示上 有些 Agent 会校验自己的 hook 文件，并拒绝运行内容变过的 hooks——Codex 会显示 **Modified since last trusted** 然后停在那里等。这一条很难受，因为 hooks *就是*状态通道： 在你回答之前，Agent 什么也不汇报，所以侧栏显示的是它最后知道的状态，而不是**需要你**。 如果一个会话看起来空闲但什么也没发生，去看那个窗格本身。回答一次提示，状态就恢复了。Fyolo 会在启动时重新写入自己的 hooks（正是这件事让别的工具没法悄悄替换掉它们），所以这个提示可能 在一次更新之后再来一次。 ## Agent 起不来，或者瞬间就退出 一个窗格立刻死掉并显示「failed to launch」，几乎总是 `PATH` 的问题，而不是 Agent 的问题。 Fyolo 通过你真正的登录 shell 启动 Agent，所以你的配置准备的一切都在——但一个装在你的配置 没加进来的位置上的命令行工具，仍然是看不见的。 打开**设置 ▸ Agents** 看那个 Agent 那一行：Fyolo 会解析你登录 shell 的 `PATH`，并把它找 不到的命令标出来。要么修你的 shell 配置，要么把绝对路径（`/opt/homebrew/bin/codex`）填进 命令字段。这个字段是按设备的，所以要在出问题的那台机器上填。 ## 状态 hooks 本来好好的，突然不工作了 Agent 的配置文件是公共地盘——别的 Agent 管理工具也往同一个 `~/.claude/settings.json` 和 `~/.codex/hooks.json` 里写，而有些是整块替换 hooks 而不是合并进去。发生这种事时，Fyolo 收不到汇报，状态就退回去读屏幕。 Fyolo 会在启动时、以及在你把它切回前台时重新写入自己的 hooks，所以在本机上这通常会自己 好。这一遍只扫本机：另一台机器上是什么样就一直是什么样，直到你去那边修——在那台机器的 **Agent** 页面上按**重新安装 Hooks 和技能**。 ## `fyolo sessions` 说 `disabled` 编排 API 是可选的。打开**设置 ▸ Agents ▸ 会话控制**，它同时会安装 `fyolo` 技能，让 Agent 知道这些命令存在。 每一个 CLI 错误都是同一个形状，并带一个非零退出码，所以脚本可以基于 `error` 分支而不用去解 散文——错误码列在 [JSON 约定](/zh-CN/docs/cli#json-contract)里。 ## `fyolo: command not found` 这个命令是应用替你装的一个软链：**设置 ▸ Fyolo server ▸ 命令行 ▸ 命令行工具**，它把 `fyolo` 链接到 `/usr/local/bin`（macOS 会问你一次）。如果开关本来就是开的，开一个新的 shell——在软链存在之前就起的会话里，`PATH` 的缓存是旧的。`fyolod` 是另一个命令，它住在 每台机器上；参见 [Fyolo server](/zh-CN/docs/server)。 ## 重启之后会话不见了 没有服务的话，server 只活到你这次登录会话结束为止。装一个，它就能扛过登出、崩溃和重启： ```bash fyolod service install fyolod service status ``` 这是远程机器上最常见的意外——那上面根本没人交互式登录过。参见 [Fyolo server](/zh-CN/docs/server)和[什么会留下来](/zh-CN/docs/persistence)。 ## 一台机器不应答了 从外往里查。如果普通的 `ssh` 都失败，Fyolo 也一样会失败——它用的是你自己的 `~/.ssh/config`，从不携带自己的凭据。 ```bash ssh mybox true # SSH 本身通不通？ fyolod list --host mybox # 那边的 server 在应答吗？ fyolod deploy --host mybox # 重装并校验一遍 ``` `deploy` 是一次对账，所以对一台状态糟糕的机器跑它是安全的。密钥是到处都能用的那种凭据， 包括给那台机器上已经在跑的会话用；一个带密码短语的密钥需要先加载进 `ssh-agent`，和任何 非交互式的 `ssh` 一样。那台机器自己的页面上有一个**测试**按钮，会说出你遇到的是哪一种 结果——参见[远程主机](/zh-CN/docs/remote-hosts#testing-the-route)。 ## iPhone 应用连不上某台机器 配对把手机绑定到一个地址上。按顺序检查： 1. **机器醒着吗？** 睡着的 Mac 什么也不应答，而且应用里没有任何东西能从外面把它叫醒。如果 你想让这件事一直成立，就配对到一台一直开着的机器上——参见 [什么会留下来](/zh-CN/docs/persistence#sleep)。 2. **发布了吗？** **设置 ▸ 手机**里那台机器必须是已发布的；在同一个 Wi-Fi 下，这就够了。 3. **在外面时，有隧道吗？** 离开你自己的网络，机器需要一个地址——**设置 ▸ 手机 ▸ 隧道**， 或者你自己的。 4. **Token 换过吗？** **更换 Token…**按设计会让每一台已配对的手机登出。重新扫一次二维码。 参见 [iOS 应用](/zh-CN/docs/iphone)。 ## 通知不出现 任务通知和其他系统权限一样：macOS 只问一次，如果当时拒绝了，应用就没法再问。去 **系统设置 ▸ 通知 ▸ Fyolo** 看一下，再确认**设置 ▸ Agent ▸ 通知**里的**任务完成**是 开着的。 它们也是有意安静的。一轮在 Fyolo 处于最前面的时候跑完，是不会通知的——你本来就在看着 它——只花了一瞬的一轮也不会。 ## 有东西不对劲，而你想要证据 server 会记录没人附着时发生过什么——而那恰恰是 bug 最爱掉进去的那段窗口。 ```bash fyolod logs -n 200 # 最近的尾部 fyolod logs -f # 实时跟着看 fyolod logs --path # 文件本身，用来提 bug ``` 在复现一个时有时无的问题？让 `fyolod logs -f` 自己占一个窗格跑着。这份日志是唯一一份 横跨了「你不在」那段时间的记录。 ## 还是卡住了 去 [github.com/fl0wo/fyolo](https://github.com/fl0wo/fyolo/issues) 开一个 issue，附上 `fyolod status` 的输出和 `fyolod logs` 的尾部。这两样回答了维护者本来要问的 大部分问题。再加上 macOS 版本、Fyolo 版本，以及会话是在本机还是在另一台机器上。