疑难排查

「Unable to connect to the daemon」

桌面应用显示 Connecting to the daemon… 之后报错——它启动的 host 没起来，或者没有在应用预期的位置应答。

先重试，再重启应用。 host 随应用启动，所以重启能解决大多数情况，提示文案本身也是这么说的。
检查是否有残留的覆盖设置。 打开 Settings → Daemon。如果「Daemon URL」有值，应用就是在指向某个特定地址而不是自动发现本地 host——清空以自动发现，或改成正确的地址。
看日志（路径见本地数据）如果一直失败；host 的启动输出会写到那里。

host 拒绝启动：「already running」

如果同一份安装启动了第二个 host，它会立刻退出并输出 [linkcode/daemon] already running (pid {pid}) at {url}。同时只运行一个——两个会把同一份本地数据库劈成两半。通常它会自行恢复；如果没有，请彻底退出 LinkCode（检查是否有残留进程）再重新启动。

host 默认监听 19523 端口，被占用时向上寻找（19524、19525，直到 19532）。若该区间全被占满，它会以 no free port for socket.io in 19523–19532 失败。腾出其中一个端口，或设置 LINKCODE_PORT 把 host 挪到别处。客户端会自动从 ~/.linkcode/runtime.json 发现真实 URL（见本地数据）。

智能体起不来

在 Settings → Agents 里看它的运行时状态：

Not installed —— 点 Download，或自行安装该 CLI。Grok Build 永远属于后一种：LinkCode 无法替你下载。
Signed out —— 点 Sign in。Claude Code 和 Codex 在浏览器中完成流程；如果页面给出的是授权码，把它粘回 LinkCode。
Unverified —— 机器上找到的安装不是当前 LinkCode 版本验证过的那一版。通常没问题；若表现异常，下载配套版本。

具体到 OpenCode，线程以 opencode: failed to start server (...) 失败意味着没找到可用的 opencode 二进制。让 LinkCode 下载一个，或自行安装到 host 能看到的位置——它的 PATH，或 ~/.opencode/bin。

Claude Code 的一轮瞬间结束且没有输出

通常是凭据过期或失效。在 Settings → Agents 重新认证，或者在终端里运行 claude 并重新登录。

终端不可用

pty sidecar not configured: terminals are unavailable on this host 表示终端辅助程序不可达。打包版应用是自带它的，因此出现这条通常意味着安装受损——重新安装 LinkCode。如果你是从源码运行 host 且没先构建该辅助程序，出现这条则属正常。

看不到拉取请求状态

Git 概览需要 host 机器上的 GitHub CLI。面板会指出缺的是哪一半：安装 gh，或运行 gh auth login。没有远端、或远端托管方不受支持的仓库，则完全不显示 PR 区块。

Simulator 面板提示配置未完成

面板会列出缺失项——Xcode 及其命令行工具、iOS runtime、模拟器设备——并在你补齐时逐项勾掉，包括替你下载 runtime（体积数 GB，请让面板开着）。模拟器仅限 macOS。某些机器能列出设备但无法串流，这时面板会直说，而不是假装已连接。

macOS Gatekeeper / Windows SmartScreen

LinkCode 的桌面版已签名并公证（macOS），或通过 Azure Trusted Signing 签名（Windows）。正常下载的正式版不应触发 Gatekeeper 或 SmartScreen 警告。如果出现，请确认你是直接从 LinkCode 的发布页下载安装包，而不是某个镜像副本。

日志在哪里

桌面应用会把 host 的输出记录到文件——macOS 上是 ~/Library/Logs/LinkCode/main.log，Windows 上是 %APPDATA%\LinkCode\logs\main.log，Linux 上是 ~/.config/LinkCode/logs/main.log。你自己从终端启动的 host 则把日志输出到那个终端。