1. 项目概述：AI编码代理的“帝国指挥官”

如果你和我一样，每天的工作流里已经离不开Claude Code、Cursor或者GitHub Copilot CLI这类AI编码代理，那你肯定也遇到过这个甜蜜的烦恼：一个代理不够用，但开多了又乱成一锅粥。想象一下这个场景：你在主分支上让Claude Code重构一个模块，同时在 feature/auth 分支上让Cursor帮你设计一个新的API，又在 hotfix/urgent 分支上让Copilot CLI快速修复一个生产环境bug。三个终端窗口来回切换，哪个卡住了、哪个在等输入、哪个刚刚把 node_modules 给删了，全靠人肉盯梢，一不小心就忘了哪个窗口在干嘛。

这就是我遇到 Agent of Empires （简称AoE）这个项目时的第一反应：它解决了一个我都没意识到自己已经忍了很久的痛点。AoE本质上是一个运行在终端里的 AI编码代理会话管理器 。它不是一个新AI，而是一个“指挥官”，帮你把Claude Code、Cursor、OpenCode、Mistral Vibe等市面上主流的命令行AI工具，像管理一支军队一样组织起来。每个代理运行在独立的、持久的 tmux 会话里，你可以通过一个统一的终端用户界面或者网页仪表盘，一眼看清所有代理的状态，随时切入任何一个进行交互，而不用担心关掉终端会话就没了。

对我来说，AoE的核心价值在于它把“并行化使用AI”这件事从一种手忙脚乱的技巧，变成了一种可管理、可监控的标准化工作流。它基于 tmux ，这意味着所有会话都在后台持久运行，你关掉AoE的界面，代理们依然在默默工作。它支持Git工作树，让不同代理可以在同一个代码库的不同分支上并行作业而互不干扰。它甚至提供了可选的Docker沙箱，为那些你还不完全信任的代理实验提供一个隔离的环境。最让我惊喜的是它的Web仪表盘和远程访问功能，这意味着我可以在沙发上用iPad，或者在外面用手机，随时查看和控制我电脑上正在疯狂编码的AI代理们。

2. 核心设计思路与架构拆解

AoE的设计哲学非常清晰： 不替代，只增强 。它没有重新发明轮子去调用AI API，而是选择成为现有优秀命令行AI工具的“粘合剂”和“调度中心”。理解这个设计前提，就能明白它为什么好用以及如何用好它。

2.1 为什么选择tmux作为底层基石？

这是AoE最聪明也最务实的选择。 tmux 是一个在Unix-like系统上久经考验的终端复用器，它的核心能力就是创建持久的、可分离的会话。AoE利用这一点，为每一个你启动的AI代理（比如一个Claude Code实例）创建一个独立的 tmux 会话。这个会话里运行的就是原生的 claude 命令。

这样做带来的好处是立竿见影的：

  1. 会话持久性 ：你关闭终端窗口、断开SSH连接、甚至电脑休眠后唤醒，只要 tmux 服务进程还在，你的AI代理会话就一直在运行。重新打开AoE，所有状态原封不动。
  2. 零侵入性 ：AoE不需要修改Claude Code或Cursor的内部逻辑。它只是帮你启动了它们，并提供了一个管理和观察的窗口。你甚至可以直接用 tmux attach -t <session-name> 命令绕过AoE，直接连接到那个会话进行操作，完全兼容你原有的 tmux 工作习惯。
  3. 资源隔离 ：每个 tmux 会话有自己的输入输出缓冲区、环境变量和进程树。这意味着一个代理崩溃了（比如内存溢出），不会影响到其他代理的会话。

AoE在 tmux 之上构建的，是一层“语义理解”。原生的 tmux 只知道有会话在运行，但不知道里面跑的是Claude还是Cursor，更不知道这个Claude现在是正在思考（Running）、在等待你输入（Waiting）、还是已经闲置了（Idle）。AoE通过解析每个会话的终端输出，结合对各个AI工具交互模式的理解，实现了 代理状态检测 。这是它价值倍增的关键。

2.2 多工作空间与隔离策略

管理多个代理，最怕的就是它们互相“打架”。AoE提供了两套成熟的隔离方案，你可以根据场景组合使用。

Git工作树 ：这是处理同一项目多分支开发的利器。当你为同一个代码仓库创建多个代理会话时，AoE可以自动为每个会话创建Git工作树。工作树是Git的一个功能，它允许你在同一个本地仓库克隆中，同时检出多个分支到不同的目录，并且每个目录都有独立的工作区。这意味着：

  • 代理A在 /path/to/repo-main 处理 main 分支。
  • 代理B在 /path/to/repo-feature 处理 feature/x 分支。 两个代理对文件的修改完全隔离，互不影响。当你完成一个分支的工作后，可以直接在工作树目录里提交、推送，然后合并回主仓库。AoE帮你自动化了工作树的创建、切换和清理，你只需要关心给代理下什么指令。

Docker沙箱 ：当你需要测试一个还不熟悉的AI代理（比如新出的某个工具），或者运行一个可能产生破坏性操作（比如 rm -rf 练习）的代理时，沙箱就至关重要了。AoE可以配置为在Docker容器内启动代理会话。容器拥有独立的文件系统、网络和进程空间。

注意：AI代理通常需要访问你的代码和配置文件（如 ~/.config 下的API密钥）。AoE的Docker方案很巧妙，它通过卷挂载（Volume Mounts）将必要的目录（如你的项目路径、认证文件目录）映射到容器内部，既保证了操作隔离，又让代理能访问到它需要的东西。你需要确保Docker已安装并正确配置，同时注意文件权限问题，避免容器内进程因权限不足无法读写挂载的文件。

2.3 统一控制层：TUI、CLI与Web Dashboard

AoE提供了三种交互界面，覆盖了从极客到小白的全部场景。

  1. 终端用户界面 ：这是核心，一个用Rust编写的、基于 crossterm 或类似库的文本界面。启动 aoe 命令即可进入。它用字符图形清晰地列出所有会话、状态、所属分支和沙箱情况。快捷键设计直观（按 ? 查看），你可以创建、删除、聚焦、暂停会话。它的“Diff视图”功能尤其好用，可以直接在TUI里浏览代理对代码的修改，甚至进行编辑，无需跳出。
  2. 命令行界面 ：为了脚本化和自动化。 aoe add --cmd cursor --branch fix-typo 一行命令就能创建一个运行Cursor在新分支上的会话。这可以轻松集成到你的CI/CD流水线或自定义脚本中，比如自动为每个新Issue创建一个诊断代理。
  3. Web仪表盘 ：这是“杀手级”功能。运行 aoe serve ，会在本地启动一个Web服务器。用浏览器打开，你就能看到一个图形化的仪表盘。 最关键的是，每个代理的真实终端被“流式传输”到了网页里 。你可以在网页上直接打字与Claude Code交互，就像在本地终端一样。这意味着你可以从任何设备（公司电脑、家里平板、手机）访问和控制你的AI代理军团。AoE甚至支持通过Tailscale Funnel或Cloudflare Tunnel配置安全的远程访问，让你真正实现“随时随地编码”。

3. 从零开始的实战部署与配置

理论说再多，不如动手装一遍。下面是我在macOS和Linux Ubuntu系统上从零部署AoE并接入Claude Code和Cursor的完整过程，包含每一步的意图和可能遇到的坑。

3.1 基础环境准备

AoE的核心依赖只有两个，一个必需，一个可选但强烈推荐。

必需依赖：tmux AoE的灵魂所在。大多数Linux发行版已经预装。如果没有，安装很简单：

# Ubuntu/Debian
sudo apt update && sudo apt install tmux

# macOS (使用Homebrew)
brew install tmux

# CentOS/RHEL/Fedora
sudo yum install tmux  # 或 sudo dnf install tmux

安装后，在终端输入 tmux -V 确认版本。建议使用3.0以上版本以获得最佳兼容性。

可选但推荐依赖：Docker 如果你想使用沙箱功能，需要安装Docker Engine。请务必参考 Docker官方文档 进行安装，因为不同系统差异很大。安装后，记得将你的用户加入 docker 用户组，以避免每次都要 sudo ：

sudo usermod -aG docker $USER

重要 ：执行此命令后，你需要 完全注销并重新登录 ，或者重启电脑，这个组权限变更才会生效。这是新手最容易忽略的一步，会导致后续运行AoE沙箱时出现“权限被拒绝”的错误。

3.2 安装Agent of Empires

AoE本身是用Rust编写的，提供了多种安装方式。最推荐的是使用安装脚本或Homebrew。

方法一：一键安装脚本（最快） 

curl -fsSL https://raw.githubusercontent.com/njbrake/agent-of-empires/main/scripts/install.sh | bash

这个脚本会自动检测你的系统架构，下载预编译好的二进制文件，放到 ~/.local/bin 目录（如果该目录在你的 PATH 环境变量中）。如果 ~/.local/bin 不在 PATH 中，脚本通常会提示你。你可以手动添加：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc  # 或 ~/.zshrc
source ~/.bashrc

然后运行 aoe --version 检查是否安装成功。

方法二：Homebrew（macOS/Linux） 如果你已经是Homebrew用户，这是最干净的方式。

brew install aoe

Homebrew会自动处理依赖和路径。

方法三：从源码构建 适合开发者或想体验最新未发布功能的人。

# 1. 安装Rust工具链 (如果尚未安装)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

# 2. 克隆仓库并构建
git clone https://github.com/njbrake/agent-of-empires.git
cd agent-of-empires
cargo build --release

# 3. 将二进制文件链接到可访问路径
sudo cp target/release/aoe /usr/local/bin/  # 或 ~/.local/bin/

从源码构建能确保你获得绝对最新的代码，但需要更长的编译时间。

3.3 配置你的AI代理工具

AoE本身不包含AI能力，它需要调用你本地已安装的AI命令行工具。你需要先安装并配置好至少一个。

以Claude Code为例：

  1. 访问Claude Code的官方GitHub仓库，按照说明安装。通常也是一条curl命令。
  2. 安装后，首次运行 claude 命令，它会引导你进行身份验证（登录Anthropic账户）。 确保你在常规终端下能成功运行 claude 并开始对话 。这是AoE能调用它的前提。
  3. （可选但重要）配置Claude Code的上下文和偏好。你可以编辑其配置文件（通常位于 ~/.config/claude-code/config.json ），设置默认模型、编辑器等。AoE会继承这些配置。

以Cursor CLI为例：

  1. Cursor的CLI工具可能需要从Cursor IDE内部启用或单独下载。请参考Cursor官方文档。
  2. 同样，先在普通终端测试 cursor 命令能否正常运行并响应。

AoE的自动发现机制 ： 安装好AoE和AI工具后，启动AoE TUI（输入 aoe ），按 n 创建新会话时，AoE会自动扫描你的 PATH 环境变量，列出所有它支持且已检测到的工具（如Claude Code, Cursor等）。如果你安装的工具没出现，请检查：

  • 该工具的可执行文件是否在 PATH 中（可用 which claude 验证）。
  • 该工具是否在AoE的支持列表内。

3.4 创建并管理你的第一个代理会话

让我们启动AoE并创建两个会话来感受一下。

# 1. 启动AoE终端界面
aoe

你会看到一个简洁的TUI界面，目前会话列表是空的。

创建第一个会话（Claude Code在主分支）：

  1. 在TUI中按 n （New）。
  2. 使用方向键或输入工具名，选择 claude （假设已安装）。
  3. 给它起个名字，比如 refactor-auth 。
  4. 在“Path”选项，输入或浏览到你的项目根目录，例如 ~/projects/my-api 。
  5. “Git Branch”留空或输入 main ，AoE会使用当前分支或指定的分支。
  6. “Sandbox”选项，初次体验可以先选 None 。
  7. 按回车确认。你会看到新会话出现在列表中，状态可能很快从 Launching 变为 Running 或 Waiting 。

创建第二个会话（Cursor在特性分支）：

  1. 再次按 n 。
  2. 选择 cursor 。
  3. 起名 design-new-endpoint 。
  4. 路径选择同一个项目 ~/projects/my-api 。
  5. 在“Git Branch”输入 feature/user-profile 。 关键在这里 ：AoE会检测到这是同一个仓库的不同分支，它会自动为你创建Git工作树。你会在项目目录旁发现一个类似 my-api_feature-user-profile 的新目录，Cursor将在这个独立的工作区中操作。
  6. 确认创建。

现在你的TUI里应该有两个会话，分别运行着Claude和Cursor，在不同的分支上工作。你可以用方向键选择会话，然后：

  • 按 Enter 键： 附加 到该会话。这时你会进入一个全屏的 tmux 会话，直接与AI代理交互，就像你单独在终端里运行它一样。
  • 在附加状态下，记住这个关键的 tmux 快捷键： Ctrl+b d 。这会让你的终端从当前的AI会话中 分离 出来，回到AoE的TUI主界面，而AI会话会在后台继续运行。
  • 在TUI主界面，按 s 可以停止（终止）一个会话，按 x 可以删除一个会话（停止并清除）。

4. 高级功能实战与深度配置

基础功能用顺手后，AoE的一些高级特性才能真正释放生产力。下面我结合自己的使用经验，详细拆解几个核心场景。

4.1 利用Git工作树实现高效并行开发

AoE的Git工作树管理是隐形的魔法。当你为同一仓库的不同分支创建会话时，它自动在后台执行了类似以下命令：

# 假设原始仓库在 /home/you/projects/my-app
# AoE为 `feature/ai-assistant` 分支创建工作树
git worktree add ../my-app_feature-ai-assistant feature/ai-assistant

这个新目录（ my-app_feature-ai-assistant ）是一个完整的、独立的Git工作区，但共享同一个 .git 仓库对象。这意味着：

  • 完全隔离 ：代理在 feature-ai-assistant 目录下的修改，不会影响 main 目录。
  • 高效同步 ：在任何工作树中拉取（ git pull ）或获取（ git fetch ）更新，其他工作树也能看到。
  • 无缝合并 ：当 feature-ai-assistant 的工作完成后，你可以在该目录内提交、推送。然后切换回主工作树（ my-app ）执行 git merge feature/ai-assistant 。

实操心得 ：

  • 命名清晰 ：在创建会话时，使用能明确描述任务的分支名和会话名，例如 feat/add-payment 和会话名 claude-payment-api 。AoE自动生成的工作树目录名会包含分支名，方便你后续在文件管理器中定位。
  • 定期清理 ：删除AoE会话时，记得选择“删除工作树”（如果选项存在），或者手动清理。长期积累未清理的工作树目录会占用磁盘空间。你可以用 git worktree list 命令查看所有工作树，用 git worktree remove <path> 手动删除。
  • 冲突处理 ：如果两个代理在不同工作树修改了同一个文件的相近行，在合并时依然会产生冲突。AoE不解决Git合并冲突，它只是提供了隔离的沙盘。合并前进行 git diff 和代码审查仍是必要步骤。

4.2 Docker沙箱配置与安全实践

对于实验性任务或运行来源不那么确定的AI工具，沙箱是必备的安全网。以下是配置Docker沙箱的详细步骤和注意事项。

1. 启用全局沙箱（谨慎）： 你可以在AoE的配置文件（通常位于 ~/.config/agent-of-empires/config.toml ）中设置默认使用沙箱。

[session]
default_sandbox = "docker" # 所有新会话默认在Docker中运行

我不建议全局开启，因为它会为所有会话增加开销。更好的方式是按需开启。

2. 创建带沙箱的会话： 在TUI中按 n 创建会话时，在“Sandbox”选项选择 Docker 。AoE会使用一个预定义的Docker镜像（通常是包含基本开发工具的轻量级Linux镜像）启动容器。

3. 理解文件挂载： 为了让容器内的AI代理能访问你的代码和配置，AoE会自动挂载一些目录：

  • 项目路径 ：你指定的项目目录被挂载到容器内的相同路径（如 /host/project ）。
  • 配置目录 ：如 ~/.config （包含Claude、Cursor等的API密钥和设置）被挂载到容器内对应用户的 .config 目录。
  • 缓存目录 ：如 ~/.cache ，用于加速。

4. 常见问题与排查：

  • 权限错误 ：容器内进程的用户（通常是 root 或非root用户）可能没有权限写入挂载的目录。解决方案是确保你的本地目录对“其他用户”有写权限（ chmod o+w 不推荐），或者更好的是，在AoE配置中指定容器以你的用户ID运行（如果AoE支持该配置）。
  • 网络问题 ：某些AI工具需要访问特定API端点。确保Docker容器有网络连接（默认的 bridge 模式通常可以）。如果公司网络有代理，需要在容器内也设置代理环境变量。
  • 性能开销 ：文件I/O通过挂载会有轻微开销，对于纯计算任务影响不大。如果代理需要大量读写小文件，可能会比原生运行慢一点。
  • 工具缺失 ：基础Docker镜像可能缺少某些工具（如特定版本的Node.js、Python包）。你需要构建自定义的Docker镜像，并在AoE配置中指定。这涉及到编写 Dockerfile 和配置AoE的 sandbox.docker_image 设置。

提示：初次使用沙箱时，可以先用一个简单的、非关键的任务进行测试。观察日志，确认AI工具能正常启动、认证和运行，再用于重要工作。

4.3 Web仪表盘与远程访问实战

Web仪表盘是AoE的“第二屏幕”，远程访问则是它的“超级武器”。

启动本地Web仪表盘： 

# 方法1: 在另一个终端标签页运行
aoe serve
# 默认访问地址: http://localhost:8080

# 方法2: 在AoE TUI中直接按 `R` (Remote)
# 这会同时启动Web服务器并在浏览器中打开页面，更便捷。

打开网页，你会看到一个比TUI更美观的界面。每个会话都有一个终端窗口嵌入在网页中。 你可以直接在网页里打字与AI交互 ，效果和本地终端几乎一致，因为背后是真正的终端流。

配置远程安全访问（以Tailscale Funnel为例）： 这才是真正让你“移动办公”的功能。你可以在咖啡馆用手机查看家里电脑上AI代理的进度。

  1. 前提 ：你需要一个Tailscale账户，并在你的电脑和手机上都安装登录了Tailscale客户端。确保你的Tailscale网络是通的。
  2. 启用Funnel ：Tailscale Funnel允许你将本地服务安全地暴露到公网。在Tailscale管理控制台为你的机器启用Funnel。这会给你一个类似 https://your-machine.ts.net 的稳定地址。
  3. 在AoE中配置 ：按 R 启动远程访问时，AoE会检测Tailscale Funnel是否可用。如果可用，它会自动配置并通过Funnel暴露Web服务。
  4. 手机访问 ：AoE TUI界面上会显示一个二维码和访问密码（Passphrase）。用手机扫描二维码，输入密码，即可在手机浏览器中安全地访问Web仪表盘。你可以将网页“添加到主屏幕”，它就像一个原生App一样工作（PWA）。

使用Cloudflare Tunnel作为备选： 如果你的网络环境不能用Tailscale，AoE也支持Cloudflare Tunnel（通过 cloudflared ）。你需要先安装 cloudflared 并登录你的Cloudflare账户，然后按照AoE的远程访问指南进行配置。原理类似，都是建立一个安全的隧道将本地端口映射到一个公网可访问的HTTPS地址。

安全提醒 ：

  • 务必使用密码 ：AoE生成的访问密码是防止未授权访问的第一道防线，不要泄露。
  • HTTPS ：无论是Tailscale Funnel还是Cloudflare Tunnel，都提供加密的HTTPS连接，数据传输是安全的。
  • 及时关闭 ：不需要远程访问时，记得在AoE TUI中停止远程服务（通常是同一个 R 键切换），关闭公网暴露。

5. 集成、优化与故障排除实录

将AoE融入你的日常开发流，并解决实际使用中遇到的问题，这部分才是真正的干货。

5.1 与现有开发工具链集成

AoE不是孤岛，它可以很好地和你已有的工具配合。

与IDE/编辑器集成 ： 虽然AoE提供了TUI和Web界面，但你大部分编码工作可能还是在VSCode或Neovim中。一个高效的用法是：

  1. 用AoE TUI或CLI创建并启动代理会话。
  2. 在你的编辑器里打开对应Git工作树的目录（ my-app_feature-xxx ）。
  3. 让AI代理在终端里运行、分析、建议，而你同时在编辑器里查看、编辑代码。两者通过文件系统同步。你可以把AoE的Web界面放在第二块显示器上，作为监控面板。

通过CLI实现自动化： AoE的CLI非常适合脚本化。例如，你可以写一个脚本，每天自动创建一个新的代理会话，对主分支代码运行静态分析或安全扫描：

#!/bin/bash
# daily-code-review.sh
SESSION_NAME="daily-review-$(date +%Y%m%d)"
PROJECT_PATH="/home/me/critical-app"

# 创建在Docker沙箱中运行的Claude Code会话，分析main分支
aoe add \
  --name "$SESSION_NAME" \
  --cmd claude \
  --path "$PROJECT_PATH" \
  --branch main \
  --sandbox docker \
  -- /bin/bash -c "echo '请分析此代码库的潜在安全漏洞和代码坏味道，输出报告。'; claude"

echo "每日代码审查会话 $SESSION_NAME 已启动。"

然后通过cron定时任务执行这个脚本。

与监控系统结合 ： AoE的会话状态（运行、等待、错误）可以通过其输出或可能的API（如果未来提供）获取。你可以编写脚本定期检查，如果发现某个会话长时间处于“错误”状态，就发送通知（如Slack消息、邮件）。

5.2 性能调优与资源管理

运行多个AI代理，尤其是像Claude Code这样可能启动大型语言模型本地实例的工具，对系统资源是考验。

内存管理 ：

  • 监控 ：使用 htop 或 glances 等工具监控内存使用。如果AI工具是本地LLM（如某些Codex CLI变体），它们可能占用数GB内存。同时运行多个实例可能导致内存耗尽（OOM）。
  • 策略 ：不要一次性启动太多内存消耗型代理。利用AoE的会话暂停（在TUI中可能对应某个快捷键）功能。暂时不用的会话可以暂停，释放其占用的资源（取决于AI工具本身是否支持优雅暂停），需要时再恢复。
  • Docker内存限制 ：如果使用Docker沙箱，可以为容器设置内存限制。这需要在AoE配置或Docker守护进程配置中设置。这能防止单个失控的代理拖垮整个系统。

CPU与磁盘I/O ： AI生成代码和文件操作是CPU和磁盘密集型的。如果多个代理同时大量读写文件（如生成代码、运行 npm install ），磁盘可能会成为瓶颈。使用 iotop 监控磁盘活动。考虑将项目放在SSD上以提升响应速度。

网络考虑 ： 如果AI工具需要调用云端API（如官方的Claude、GPT），那么网络延迟和稳定性会影响代理的响应速度。确保网络连接良好。对于关键任务，考虑使用网络质量更好的环境。

5.3 常见问题排查与解决方案

以下是我在实际使用中踩过的坑和解决方案，希望能帮你节省时间。

问题一：启动AoE或创建会话时报“tmux”错误。

  • 症状 ： Failed to create tmux session 或 tmux command not found 。
  • 排查 ：
    1. 确认 tmux 已安装： which tmux 。
    2. 确认 tmux 在AoE的运行环境中可用。如果你通过某些包管理器或从源码安装，确保安装路径在系统的 PATH 环境变量中。
    3. 尝试在同一个终端里直接运行 tmux new-session -s test ，看是否能正常创建会话。如果不能，是你的 tmux 安装或配置有问题。
  • 解决 ：重新安装 tmux ，或检查shell配置文件（ .bashrc , .zshrc ）中是否有错误的 PATH 设置。

问题二：AI代理在会话中启动失败，状态显示“Error”。

  • 症状 ：会话创建成功，但很快状态变为Error。
  • 排查 ：
    1. 在AoE TUI中选中该会话，查看其日志（通常有快捷键如 l for Logs）。错误信息会提示原因。
    2. 常见原因：
      • AI工具未安装或不在PATH ：在普通终端手动运行 claude 或 cursor ，看是否成功。
      • 认证失败 ：AI工具需要API密钥或登录。在普通终端先完成首次认证流程。
      • 沙箱环境问题 ：如果是Docker沙箱，可能是镜像拉取失败、权限不足或挂载路径错误。查看Docker日志： docker logs <container-id> （AoE日志中通常会显示容器ID）。
  • 解决 ：根据日志逐一解决。对于沙箱问题，尝试先在主机上不使用沙箱运行代理，确认工具本身正常，再排查Docker配置。

问题三：Web仪表盘无法访问或终端不显示。

  • 症状 ： aoe serve 后浏览器打开页面空白或终端区域黑屏。
  • 排查 ：
    1. 检查端口占用：AoE默认用8080端口。 lsof -i:8080 查看是否被其他程序占用。
    2. 检查防火墙：本地防火墙可能阻止了8080端口的访问。
    3. 检查浏览器控制台：按F12打开开发者工具，看是否有JavaScript错误或WebSocket连接失败。
    4. Web终端依赖WebSocket。确保你的网络环境（特别是公司代理）不阻止WebSocket连接 ( ws:// 或 wss:// )。
  • 解决 ：指定其他端口 aoe serve --port 9090 。配置防火墙规则允许端口访问。对于复杂的代理环境，可能需要配置AoE的Web服务器使用正确的代理设置（如果支持）。

问题四：通过SSH（特别是手机SSH客户端）使用AoE时，附加到会话后无法返回TUI。

  • 症状 ：在手机SSH客户端（如Termius）里运行 aoe ，进入一个代理会话后，按 Ctrl+b d 没反应，回不到AoE主界面。
  • 原因 ：某些移动端SSH客户端对 tmux 的快捷键映射支持不佳，或者 Ctrl 键组合被客户端拦截。
  • 解决 ：
    1. 最佳实践 ：在通过移动SSH连接时，先创建一个 tmux 会话，然后在里面运行 aoe 。 
      # 连接到服务器后首先执行
tmux new-session -s aoe-mobile
# 然后在新的tmux会话中启动aoe
aoe
      这样，即使你从代理会话分离（ Ctrl+b d ），你也是回到这个 tmux 会话的 aoe 界面，而不是被SSH客户端断开。
    2. 如果还是不行，可以尝试修改 tmux 的前缀键（prefix），但AoE可能依赖默认的 Ctrl+b 。更简单的方法是，在附加到代理会话后，如果需要退出，可以尝试在代理自己的命令行里输入 exit 来结束代理进程，这样会话会终止，你也会自动回到AoE界面（状态变为Stopped）。

问题五：Git工作树混乱或残留。

  • 症状 ：删除AoE会话后，对应的物理工作树目录仍然存在。
  • 解决 ：AoE在删除会话时可能没有自动清理工作树（取决于版本和配置）。需要手动清理： 
    # 进入项目主仓库目录
cd /path/to/main/repo
# 列出所有Git工作树
git worktree list
# 删除不再需要的目录
git worktree remove /path/to/worktree-directory --force
    养成定期检查的好习惯。

AoE这个工具彻底改变了我管理AI编码助手的方式。从最初的手忙脚乱到现在的井井有条，它带来的不仅仅是效率提升，更是一种心智负担的减轻。我不再需要记住哪个终端窗口对应哪个任务，也不再担心关掉终端会中断一个漫长的代码生成过程。Web远程访问功能让我能在离开电脑时依然保持对进度的掌控，这种自由度在以前是无法想象的。

如果你也经常同时使用多个AI编码工具，我强烈建议你花一个小时试试AoE。它的学习曲线非常平缓，核心的TUI操作几分钟就能上手，而它带来的工作流优化是长期且深远的。从今天开始，让你手下的AI代理们，从散兵游勇变成一支听你号令的帝国军团吧。

Logo
DeepSeek技术社区

欢迎加入DeepSeek 技术社区。在这里，你可以找到志同道合的朋友，共同探索AI技术的奥秘。

更多推荐

cover

面试必看！AI Agent 八大核心概念一网打尽，轻松应对技术面试！

avatar DeepSeek技术社区
cover

毕业论文写作辅助工具推荐：哪些 AI 工具是真的靠谱好用（能够生成题目、提纲、真实参考文献、图表、公式、模型图、初稿、在线修改、降重、答辩 PPT 等）

avatar DeepSeek技术社区
cover

AI Agent 9秒删库跑路？Cursor安全红线警示录

avatar DeepSeek技术社区