# 排查问题

先分清问题出在启动配置、CLI 本身，还是模型服务。

## 查看 Facade 将使用的启动配置

在命令面板运行 **Show Agent Launch**，选择工作位置。报告会列出每个 CLI 在所选位置的启动方式：可执行文件、目录、参数和环境变量名，私有值会被隐藏。

报告说的是当前配置下的下一次启动，不是已经在运行的 Agent。请求成功时，可以到服务商的用量记录里确认是哪个账号处理的。

## 按现象查

| 现象 | 检查什么 |
| --- | --- |
| 找不到配置文件 | 选择 Open Settings，再在 Facade: Home 下选 Edit in facade.json。远端窗口以 JSON 形式打开 Settings 时，这个命令直接打开 facade.json。 |
| New Agent 里没有这个条目 | 检查条目名和 `type`，确认没有用 `enabled: false` 关掉它。无效条目会出现在 Unavailable 下，并附原因。 |
| 找不到可执行程序 | 在项目运行的环境里安装 CLI，或者在 `command` 里写完整路径。OpenCode 需要版本 2（`@opencode/cli`）。 |
| 环境变量引用不存在 | 变量必须在 Agent 启动前就存在于编辑器宿主的环境中。在已经打开的终端里 export 不会更新宿主环境。 |
| 参数与 Facade 管理的选项冲突 | 把该选项从 `args` 里去掉，改用 `model`、`effort` 或顶层的 `yolo`。 |
| 认证失败或模型不可用 | 向服务商核对密钥、地址、区域、模型 ID 和账号权限。 |
| Codex 的服务商没有响应 | 确认它的接口支持 Responses API。 |
| Agent 找不到另一个 Agent | 确认两个项目通过同一个 Facade home 连接，并且访问设置允许通信。 |
| custom 程序收不到消息 | 直接往它的终端里输入。custom 条目不接收 Facade 消息，也没有 Facade 工具。 |
| 保存的配置没有影响运行中的 Agent | 启动一个新 Agent。想保留对话，先结束 Agent，再用 Resume Agent 按新配置重启它。 |

SSH 的配置问题看[在远端机器上运行 Agent](https://facadecode.com/zh-cn/docs/remote-ssh/)；手机连接的问题看[从手机继续会话](https://facadecode.com/zh-cn/docs/remote-control/)。

## 报告问题

写清楚你试过什么、完整的报错、操作系统、编辑器和扩展版本、CLI 版本，以及选中的条目。方便的话附上相关配置，删掉密钥和私有值。

[提交 GitHub Issue ↗](https://github.com/y5ez3g/facadecode/issues)