疑难排查

「Unable to connect to the host」

桌面先显示 Connecting to the daemon…，然后显示 Unable to connect to the daemon ({url}). Run {command} first. —— 它要找的 host（即 LinkCode daemon）没有响应。

两种可能的成因：

• 还没有 host 在运行。 按快速上手启动一个 —— 应用内的提示目前指向的是源码检出下的原始开发者命令，只有当你确实是这样启动 host 时它才说得通。
• 有一个 host 在运行，但其 URL 与客户端预期的不同。 打开 Settings → Connection，检查「Daemon URL」字段（留空以自动发现，或填入正确的 URL），保存以重新连接。

Host 拒绝启动：「already running」

如果你试图启动第二个 host，它会立即以 [linkcode/daemon] already running (pid {pid}) at {url} 退出（或者，如果它已进行到探测端口的阶段，则为 another linkcode daemon (pid {pid}) is already listening at {url}）。每台机器只运行一个 host —— 第二个会分裂同一个本地数据库。把你的客户端指向已有的 host，而不要再启动一个；如果你确实想重启，就先停止已有进程。

端口已被占用

host 默认监听端口 19523，若有别的东西占用它，则向上探测（19524、19525…… 直到 19532）。如果该范围内每个端口都被占用，它会以 no free port for socket.io in 19523–19532 失败。客户端无需知道哪个端口最终胜出 —— 它们会从 ~/.linkcode/runtime.json 自动发现真实的 URL（参见 Local data）。

终端不可用

打开终端时失败，报错 pty sidecar not configured: terminals are unavailable on this host。这在今天打包后的桌面构建中是预期行为 —— 终端的 sidecar 进程还没有随发布版打包。当你从源码运行 host、并已构建 sidecar 且配置好其路径时，它可以工作。参见 panels 和已知限制。

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

这是一个已知问题：如果 Claude Code 的凭据已过期或无效，LinkCode 目前会显示一个看起来正常、但内容为空的一轮，而不是报错 —— 什么都没发生，也没有任何解释。请在终端运行 claude 并重新登录以重新认证，或确保在 host 运行所处的环境中设置了有效的 API key。（应用内用于输入 API key 的 Agents 设置界面在桌面上还不可用。）

粘贴的图片从 prompt 中消失

这在今天是预期行为 —— 图片和其他非文本附件目前不会转发给任何 Agent。参见已知限制。

OpenCode：「failed to start server」

OpenCode 启动线程失败，报错类似 opencode: failed to start server (...)。OpenCode 是唯一一个不随 LinkCode 打包的 Agent —— 你需要安装 opencode CLI，并让它在运行你 host 的进程的 PATH 中可见。设置方法参见 OpenCode。

macOS Gatekeeper／Windows SmartScreen

LinkCode 的桌面构建经过签名与公证（macOS），或通过 Azure Trusted Signing 签名（Windows）。在正确下载的发布构建上，你不应看到 Gatekeeper 或 SmartScreen 警告。如果你看到了，请确认你是直接从 LinkCode 的 GitHub 发布页下载的安装程序，而不是某个镜像副本。

日志在哪里？

目前还没有日志文件。host 会把一切打印到启动它的那个进程的 stdout/stderr —— 如果你是自己从终端启动它的（参见快速上手），那个终端窗口就是你的日志所在。