90% 的问题用以下三步定位： mira status — 配置与 provider 是否健康。 看 ~/.mira/logs/agent-service.log 最近 50 行。 直接打开有问题项目的 ~/.mira/workspace/PRJ-xxxx/task_plan.json ，对比 UI 显示。 症状 ：右上角连接指示长时间灰/红；项目列表加载转圈。 如果你连接的是 远程部署的 mira-agent / mira gateway ，先优先排这两件事： 先检查远程服务器和本地电脑的防火墙 / 安全组 远程服务器是否允许 18790 （或你自定义的端口）入站？ 你本地电脑所在网络、公司 VPN、云服务器安全组、系统防火墙是否拦了这个端口？ 最直接的测试方式是在本地电脑上执行： curl http://<remote-host>:18790/api/health 如果这里都超时或拒绝连接，UI 一定也连不上。 远程服务器是否允许 18790 （或你自定义的端口）入站？ 你本地电脑所在网络、公司 VPN、云服务器安全组、系统防火墙是否拦了这个端口？ 最直接的测试方式是在本地电脑上执行： curl http://<remote-host>:18790/api/health 如果这里都超时或拒绝连接，UI 一定也连不上。 局域网内访问远端机器时，后端必须监听 0.0.0.0 ，不能只绑 127.0.0.1 如果远端日志里看到的是： Starting mira gateway on 127.0.0.1:18790 那就只允许服务器本机访问，局域网内其他机器看不到。 应改成： mira gateway --host 0.0.0.0 --port 18790 或安装服务时： mira-engine install-service --host 0.0.0.0 --port 18790 这样局域网内其他机器才能通过 http://<server-ip>:18790 连上。 如果远端日志里看到的是： Starting mira gateway on 127.0.0.1:18790 那就只允许服务器本机访问，局域网内其他机器看不到。 应改成： mira gateway --host 0.0.0.0 --port 18790 或安装服务时： mira-engine install-service --host 0.0.0.0 --port 18790 这样局域网内其他机器才能通过 http://<server-ip>:18790 连上。 注意： 0.0.0.0 适合局域网 / 内网可达场景； 不要 把未经鉴权的 18790 直接暴露到公网。 后端起了吗？ curl http://localhost:18790/api/health # 期望返回 {"status":"ok",...} 端口对吗？UI 的 VITE_API_URL / VITE_WS_URL 与 mira gateway --port 一致？ 如果是远程 / 局域网访问，确认后端绑定的不是 127.0.0.1 ，而是 0.0.0.0 。 跨域被挡了吗？自托管反代时 nginx 的 /ws location 必须带 Upgrade / Connection: upgrade ，详见 自托管部署 。 防火墙 / VPN 拦了 18790？ lsof -iTCP:18790 -sTCP:LISTEN 验证后端在听；浏览器 DevTools → Network → WS 看握手响应码。 2. 项目状态不一致（UI vs 文件） ​ 症状 ：UI 显示 Running，但 task_plan.json 里 status: completed ；或反过来。 在项目页点 “刷新计划”，强制走 REST 重拉。 不行就重启 UI（Web 模式刷浏览器；Desktop 模式 Cmd/Ctrl+R ）。 还不行就以 task_plan.json 为准。可能是 WS 短暂断开漏推。 长期反复出现 → 检查后端日志中 task_plan.update 事件是否正常发出。 详见 实时同步机制 与 任务计划与状态同步 。 3. Provider 401 / 403 / “Unauthorized” ​ mira status 看 provider 是否被识别（key 显示前缀即正常加载）。 直接 curl 验证 key 本身有效（OpenAI / Anthropic 都有最小测试 endpoint）。 provider: "auto" 时是不是被自动匹配到了错的家？显式写 provider: "openrouter" 等。 Azure OpenAI 必须给 apiBase + extraHeaders.api-version ；model 字段是 deployment 名而非模型名。 详见 Provider 与运行时参数 。 4. “实验都完成了但项目没 completed” ​ 核心结论 ：项目 completed 不是看实验，是看 最终结果交付物存在 。 task_plan.json.result.output_path 是否非空？ result.output_type 是否在 experiment_report / paper_article / presentation / metadata 之内？ output_path 指向的文件在磁盘上真的存在？ 任一条不满足 → 进 Result 阶段重新触发一次导出。 5. guardrail 反复提示缺字段 ​ 在 实验详情面板 定位是哪几个字段缺。 直接在 UI 里给出具体文字（不要写 TODO / 待补充 ，guardrail 把它们当“没填”）。 如果 strict 太严打扰节奏，临时切回 contract_version: v1 走完探索期，再升回 strict 让 guardrail 一次补齐。 自动修复 3 次仍失败 → 切到 manual 模式，给 Agent 一段补充 prompt 指明该字段含义。 详见 Guardrail 与自动修复 。 6. 端口被占（5173 / 18790 / 8900） ​ UI 端要同步 VITE_API_URL / VITE_WS_URL 。 7. Channel 配完没反应（Telegram / 飞书 / Slack） ​ mira channels status 显示该 channel 是 connected 吗？ 看 ~/.mira/logs/agent-service.log 中以 channel 名开头的行（如 telegram: ... ）。 群里只 “@bot” 还是普通消息？ groupPolicy: mention 必须 @； open 才响应所有消息。 allowFrom 里有没有把你自己加进去？空数组 = 不限制；非空 = 严格白名单。 飞书事件回调 401 → 仔细比对 verificationToken / encryptKey ，注意尾部空格。 Slack socket 模式不需要公网； events 模式必须有公网回调地址。

详见 Channel 配置 。 8. Windows CI / 本地有 Event loop is closed 警告 ​ 这是 Windows ProactorEventLoop 在子进程清理时的已知 noise， 测试本身是通过的 ，但 GitHub Actions 因为字符串里有 Error: 把它误标成 Error。 mira 仓库的 pyproject.toml 已经加了 filterwarnings 抑制它： 如果你 fork 后跑测试还看到这条，确认本地 pyproject.toml 与上游同步即可。 9. mira agent 卡在某一步、不出输出 ​ 加 --logs --verbose 重跑，看到底卡在哪个工具调用。 是 web.search 卡住？检查代理 / 公司网；或换 provider: duckduckgo 试试。 是 exec 卡住？先确认是不是某条 shell 在前台跑长任务被 timeout 卡死—— tools.exec.timeout 默认 60s、上限 600s。 真长任务 （训练 / 大数据预处理 / 长仿真）应该让 agent 调 exec(command="...", background=true) ，job 落到 <workspace>/.mira/jobs/<job_id>/ ，再用 bg 工具 tail / wait / kill ，不会再阻塞 loop。详见 后台长任务 。 是 LLM 调用卡住？看 provider 是否限流；切到候选模型。 10. 从 MedPilot 升级后没自动迁移 ​ 正常情况下第一次跑 mira 任意命令时会自动迁移。如果没生效（最常见原因：你新机器上 ~/.mira/ 已经存在，迁移会跳过避免覆盖）： 环境变量类似：把 shell rc 里所有 MEDPILOT_* 改成 MIRA_* 。 11. UI localStorage / 设置丢了 ​ UI 设置存在浏览器 localStorage ，key 为 mira-ui-settings 。从 MedPilot 升级时会自动从 medpilot-ui-settings 拷贝过来。 如果手动清理过浏览器缓存，需要重新在设置页配置 API 地址 / 主题等；项目数据本身在后端 ~/.mira/workspace/ 不会丢。 12. Docker 起不来： Mounts denied / 权限错误 ​ macOS Docker Desktop 默认只允许挂载 /Users 等几个目录。如果你把 workspace 放在 /data/ ，需要在 Docker Desktop → Settings → Resources → File Sharing 添加。 Linux 上常见是 SELinux / AppArmor。临时排查： docker compose up -d --user $(id -u):$(id -g) ，确认非权限问题后再调 SELinux 策略。 13. Ollama / 本地模型连不上 ​ 没返回 → Ollama 没起， ollama serve 一下。 返回空数组 → 还没拉模型， ollama pull qwen2.5:14b 。 在 Mira 里报 model not found → agents.defaults.model 写的名字必须和 ollama list 完全一致（带 tag，例如 qwen2.5:14b ）。 14. mira-engine 装为系统服务后，重启电脑没自启 ​ 详见 本地服务（mira-engine） 。 15. 改完 config.json 没生效 ​ 症状 ：编辑了 ~/.mira/config.json （换模型、加 key、改 channel），但行为没变。 根因 ：gateway 进程 只在启动时读一次 config ，没有热重载。 macOS 上单跑 mira-engine start 也行（ launchctl kickstart -k 自带 restart 语义），Linux/Windows 上 start 不会强制重启已运行的进程，必须先 stop 。 不要用 uninstall-service + install-service 来"应用配置"——那是给"换注册的 host/port"或"彻底退役"用的。完整的两层模型见 本地服务（mira-engine） 。 16. 项目里没有 .venv ，agent 还在用全局 Python ​ 症状 ：开了「项目级 Python venv 隔离」这个特性，但 ~/.mira/workspace/PRJ-xxxx/ 下找不到 .venv/ ；agent 跑 pip install 装到了全局 site-packages。 根因 ：这个特性默认是关的， tools.exec.python.manager 默认值是 "off" ，需要显式改成 "uv" 。 修法是在 ~/.mira/config.json 里： 前置条件：本机 PATH 上要有 uv >= 0.5.0 （ brew install uv 或参考 uv 安装文档 ）。 MIRA 桌面 bundle 自带 uv ，源码安装需要自己装；没装而 manager 又设成 "uv" ，第一次触发时会抛 PythonEnvError: uv is required ... but was not found 。 完整字段说明见 项目级 Python venv 隔离 。 manager 还有一个 "system" 选项是 schema 里 预留 的（passthrough：不建 venv，仅 pin 解释器），当前版本 尚未实现 ，写了等同 "off" 。 跑一次 mira-engine doctor --export ，把 ~/.mira/runtime/diagnostics/<timestamp>.zip 附上。 在 GitHub Issues 搜一下关键词；没人提过就开新 issue，附 mira --version + 操作步骤 + 上面那份 zip。 紧急情况下回退到上一个稳定版本： pip install "mira-engine==<上一稳定版本>" ，UI 同步降版本——参考 mira-ui 仓库根目录的 compatibility.json （ min_agent_for_ui 给出最低 agent 版本， agent / ui 给出当前 release train 的配对）。 2. 项目状态不一致（UI vs 文件） 3. Provider 401 / 403 / “Unauthorized” 4. “实验都完成了但项目没 completed” 5. guardrail 反复提示缺字段 6. 端口被占（5173 / 18790 / 8900） 7. Channel 配完没反应（Telegram / 飞书 / Slack） 8. Windows CI / 本地有 Event loop is closed 警告 9. mira agent 卡在某一步、不出输出 10. 从 MedPilot 升级后没自动迁移 11. UI localStorage / 设置丢了 12. Docker 起不来： Mounts denied / 权限错误 13. Ollama / 本地模型连不上 14. mira-engine 装为系统服务后，重启电脑没自启 15. 改完 config.json 没生效 16. 项目里没有 .venv ，agent 还在用全局 Python