Agent Deck避坑指南：8个实战中踩过的坑和避坑方法

Agent Deck 实战指南系列写完了，但真正用起来，坑比教程里写的要多。 这篇不是系列的一部分，是一份避坑清单。基于实际使用中踩过的雷，每条都附避坑方法。

坑一：Windows 直接双击运行，闪退

Agent Deck 是 TUI 程序，依赖终端环境。Windows 用户如果直接下载 .exe 双击运行，大概率闪退或卡住。 **避坑**：Windows 用户必须用 WSL2 或 Git Bash 运行。在 WSL2 里 `curl` 安装后直接 `agentdeck` 启动。如果你连 WSL2 都没装，先去 Microsoft Store 装一个 Ubuntu，别想着原生 Windows 能跑。

坑二：Conductor 在外面打不开

教程里写了 `conductor start` 会返回一个本地地址。很多人以为这个地址手机直接能开，结果在外面连不上。 **为什么**：Conductor 默认只监听本机网络（localhost 或局域网 IP），不在公网暴露。手机和电脑不在同一个 WiFi，自然连不上。 **避坑**： - 同一 WiFi 下：用电脑局域网 IP（不是 127.0.0.1），手机才能访问 - 不同网络（比如在公司想看家里电脑）：配 Tailscale 或 Cloudflare Tunnel，把本地端口映射到公网 - 不要图省事把端口直接暴露到公网不加认证，Conductor 没有内置登录保护

坑三：Git Worktree 里 rebase，其他 worktree 炸了

教程⑤写了 Worktree 可以并行多分支。但如果你在一个 worktree 里对某个分支做了 `rebase` 或 `force push`，其他 worktree 里 checkout 同一个分支的状态会直接乱掉。 **避坑**： - 正在用的分支，不要在另一个 worktree 里动它 - 如果要 rebase，先确认没有其他 worktree 占用这个分支 - 不确定就 `git worktree list` 看一下谁在用哪个分支

坑四：同一文件两分支都改，冲突照旧

Worktree 不是魔法。两个分支改了同一个文件的同一行，merge 或切换时还是会冲突，得手动解。 **避坑**： - Worktree 适合"不同文件/不同模块"的并行开发 - 如果两个任务都要动同一个核心文件，别用 Worktree 分开，老老实实一个分支做完再做另一个 - 解冲突用 `git merge` 或编辑器，Agent Deck 不帮你解冲突

坑五：Agent Deck 不知道 Token 单价

成本追踪只能告诉你"用了多少 Token"，但 DeepSeek 和 Claude 差多少钱，它算不出来。 **避坑**： - 单价信息在 GenHub 里（用量统计 + Provider 配置） - 想看完整成本，两个工具配合用：Agent Deck 看实时消耗，GenHub 看单价和总账 - 别指望 Agent Deck 单独给你算钱

坑六：换电脑，会话状态全没了

Agent Deck 的会话状态存在本地，不跨设备同步。你在家跑了一半的会话，到公司新电脑打开 Agent Deck，是空的。 **避坑**： - 重要会话记一下项目路径和进度，换电脑后重新打开对应目录 - 跨设备同步在 roadmap 上，但还没上线，别等 - 用 Git 做代码版本管理，会话状态丢了大不了重跑，代码不会丢

坑七：工具没在 PATH 里，Agent Deck 扫不到

第一次启动 Agent Deck 会自动扫描已安装的 AI 编程工具。如果你的 Claude Code 装在 nvm 或某个非标准路径，而那个路径没加入系统 PATH，Agent Deck 扫不到。 **避坑**： - 安装 AI 工具后用 `which claude` / `which codex` 确认在 PATH 里 - 不在 PATH 就把它加进 shell 配置文件（.zshrc / .bashrc） - 重启终端让配置生效，再启动 Agent Deck

坑八：多个会话同时跑，终端被抢占

Agent Deck 管理会话，但底层还是共用一个终端环境。多个 Claude Code 同时跑长任务，输出会混在一起，你看不清哪个在说什么。 **避坑**： - 用分组功能把不同项目的会话分开 - 长任务尽量串行，或至少错开启动时间 - 用 Conductor 手机端远程看状态，不在电脑前盯着

一个总原则

Agent Deck 是管理工具，不是执行工具。它帮你看清"哪些在跑、花了多少、卡在哪了"，但不替你写代码、不解冲突、不算单价。 把它的职责边界搞清楚，踩坑会少一大半。 这篇文章基于实际使用和官方文档整理。