用tmux打造Claude Code多Agent并行开发工作流

你有没有遇到过这种场景一个终端窗口里Claude Code正在大段大段地生成接口代码另一边你还想开一个Agent去查日志、写单元测试、或者做代码审查。人肉切换来回折腾会话一多自己都分不清哪个终端在干什么。我最近就把这套流程彻底理顺了——给Claude Code配了个“总管”用终端复用工具把多个AI Agent按项目、按任务拆成独立“工位”再配合会话机制、目录隔离和一套启动脚本统一管理。这套方案不挑系统Ubuntu和macOS都能用对新手也很友好不需要懂什么复杂的原理照着配就能用。这篇文章会把这套“多Agent共治”的完整思路讲清楚为什么终端里需要同时跑多个Agent、Claude Code的会话模型是怎么回事、终端复用工具怎么选怎么配、多个Agent之间怎么做到互不干扰以及我一路上踩过的坑。1. 先想清楚为什么终端里需要同时跑多个Agent1.1 一个Agent根本不够用很多朋友刚开始用Claude Code时的习惯是一个终端窗口启动一个会话把需求一股脑往里灌。一开始还好但项目一复杂就立刻露馅。举个例子。你在改一个订单服务的接口前端也在等联调后端有个bug要复现。这时候如果只开一个Claude Code会话你让它改接口它可能会东一榔头西一棒子把上下文搞得乱七八糟你想让它同时盯着日志文件分析报错它又没有“第三只手”去实时监控。更麻烦的是不同任务的上下文会互相污染——上一个任务残留的信息会影响下一个任务的判断典型的“串味”。所以我在实际项目里跑两到三个Claude Code实例是常态一个负责主力开发一个负责看日志和排查问题一个负责做代码审查或者写测试。这里面有个前提就是它们必须能“并存”互不抢终端、互不干扰会话历史最好还能快速切换、一眼看出谁在干什么。1.2 “总管”到底管什么我给这套体系起的名字叫“总管”听起来玄乎其实它管的就三件事第一管“空间”——多个Agent需要多个独立的终端窗口/面板不能挤在一个终端里互相刷屏。第二管“身份”——每个Agent要有自己的工作目录、专属说明文件和工具配置让它知道自己是谁、该干什么。第三管“启动”——一条命令把所有Agent按预定布局拉起来而不是每次手动打开好几个终端再一个个敲启动命令。这三件事拆开看都不复杂但合在一起就是一套完整的“多Agent工作流基座”。下面我从Claude Code本身的特性讲起再逐步把“总管”搭起来。2. 先搞懂管理对象Claude Code的会话与上下文机制2.1 Agent到底是什么它跟普通AI模型有什么不同在进入实操之前我多嘴说一个很多新人会问的问题“Claude Code是AgentDeepSeek只是个模型这俩到底什么关系”你可以这么理解模型就像是刚毕业的高材生知识丰富但没手没脚你问什么它答什么但没法自己去干活。而Agent是给这个高材生配了电脑、终端、文件柜和任务清单让它能自己看代码、跑命令、改文件、查文档。Claude Code本质上就是“模型 工具权限 工作记忆 执行循环”的组合体。这个区别很关键因为它决定了你在终端里管理Agent时关注的不是“模型有多强”而是“Agent的工具有没有配好、记忆有没有隔离、执行循环有没有被打断”。这也是后面所有配置工作的出发点。2.2 Claude Code的会话、断点续传和分支Claude Code本身的会话管理能力是“总管”方案的地基。它有几个关键机制会话Session每次启动claude命令就是一个独立会话。会话内容会记录在本地的历史文件里。断点续传会话中断后可以用claude --resume回到最近的会话或者用claude --resume 会话ID回到指定会话。继续执行用claude -c 继续刚才的任务可以在当前会话基础上追加指令。分支用claude --fork 会话ID可以从某个历史会话分叉出去开一条新线。这些机制非常实用因为它们在底层已经把“多Agent并行”的基础打好了。每个Agent可以是一个独立的会话互不干扰任务做到一半想换个方向也不用推倒重来直接fork一个新会话就行。不过有一点要注意会话历史是跟当前目录关联的。如果你在同一个目录下开多个Claude Code会话虽然会话文件是分开的但Claude Code在读取项目上下文时会共用同一套项目文件容易造成交叉影响。所以“一个目录一个Agent任务线”是我一直在强调的隔离原则具体怎么做下一章讲。3. 终端复用给每个Agent一个独立“工位”3.1 为什么选tmux而不是多开终端标签页管理多个终端会话市面上其实有两种思路。一种是多开终端窗口或标签页比如iTerm2开Tab、Tabby开多个Pane也能用Ctrl数字切换。好处是零学习成本坏处是这些标签页和SSH会话之间的关联很脆弱——你一旦关掉整个终端窗口所有Agent进程跟着遭殃而且不同会话之间复制粘贴、布局调整都很麻烦。另一种就是终端复用器我用的是tmux。tmux的核心价值是终端进程和显示窗口解耦。你把Claude Code启在tmux里跑着哪怕把整个终端App关掉tmux服务还在后台重新打开终端就能原样恢复Agent会话不会中断。这一点对长时间运行的Agent任务来说太重要了。还有个附加好处tmux天然适合远程开发。你在本地起一个tmux session里面开着Claude Code本地网络断了、SSH断了回来一attach一切照旧。这个特性我后面在排查问题时还会提到。3.2 tmux的三层结构会话、窗口、窗格tmux的逻辑其实特别简单就三层Session会话相当于一间办公室每个办公室有自己的编号和名称。Window窗口相当于办公室里的工位一个session可以有多个window。Pane窗格相当于工位上的显示器一个window可以横竖切分成多个pane。我的多Agent布局习惯是一个大的tmux session叫agent-ctrl里面按业务线分若干个window每个window再切几个pane。比如agent-ctrl下有frontend、backend、review三个window每个window里跑一个独立的Claude Code实例。安装很简单Ubuntu下用aptmacOS下用brew# Ubuntu / Debian sudo apt install tmux # macOS brew install tmux安装完事启动一个sessiontmux new -s agent-ctrl然后你就可以在session内部创建window、切分pane了。我把最常用的快捷键列在下面这几个记熟就够了操作快捷键新建窗口Ctrlb c切到下一个/上一个窗口Ctrlb n/Ctrlb p横向切分窗格Ctrlb 纵向切分窗格Ctrlb %在窗格间切换Ctrlb 方向键关闭当前窗格/窗口Ctrlb x/Ctrlb 重新命名窗口Ctrlb ,脱离会话程序继续跑Ctrlb d重新接回会话tmux attach -t agent-ctrl3.3 让tmux更贴手的配置默认tmux有几个地方我用不惯鼠标滚轮不生效、窗格没有标题、新建的窗口编号是乱的。我的~/.tmux.conf里有三行配置能解决80%的体验问题set -g mouse on set -g pane-border-status top set -g pane-border-format #{pane_index} #{pane_current_command}第一行开启鼠标支持滚轮可以翻历史、点窗格可以直接切过去。第二行和第三行会在每个窗格顶部显示一个状态条显示当前窗格跑的是什么程序。这一招对多Agent管理特别有用——你一眼就能看到哪个窗格在跑Claude Code哪个窗格在跑日志工具不至于切了半天找不着北。4. 配置隔离让每个Agent各司其职4.1 用目录和CLAUDE.md区分Agent身份有了tmux“空间隔离”解决了但“身份隔离”还需要配置。打个比方tmux给每个Agent分了张桌子但桌上摆什么文具、工牌上写什么职位还得你自己放。Claude Code在每次启动时会读取当前工作目录下的CLAUDE.md文件作为项目的长期记忆和角色说明。这就是天然的“Agent身份卡”。我的做法是给不同的Agent任务线建不同的工作目录每个目录里放一份专属的CLAUDE.md。比如我有一个/home/me/work/order-backend目录里面的CLAUDE.md会写# 角色定位 你是这个订单服务的后端开发助手负责接口开发、bug排查和性能优化。 # 工作规范 - 修改代码前先阅读现有模块结构遵循项目分层规范 - 运行测试使用 make test 命令 - 涉及数据库变更时必须先输出变更SQL确认后再执行 # 常用命令 - Dev Server: make dev - 单测: go test ./... - 查看日志: tail -f /tmp/order-service.log而在另一个/home/me/work/code-review目录里CLAUDE.md则是另一个身份“你负责代码审查只读代码不改代码发现问题按严重程度输出报告”。这样两个Agent虽然都是Claude Code但启动后读到的指令完全不同行为模式有本质区别。这里有个容易踩的坑不要在项目根目录之外放共享的全局CLAUDE.md来约束所有Agent否则每个Agent都会背负相同的行为模式分分钟串味。按项目、按任务线拆分才是最整洁的做法。4.2 环境变量和MCP配置的差异化除了目录和CLAUDE.mdClaude Code还支持通过环境变量和MCPModel Context Protocol配置来区分Agent的“能力范围”。先说环境变量。Claude Code支持很多环境变量来控制模型选择、最大思考轮数、输出格式等。比如在某个Agent窗格里启动之前你可以先声明环境变量再启动export ANTHROPIC_MODELclaude-sonnet-4-5 export CLAUDE_CODE_MAX_OUTPUT_TOKENS8000 claude这样这个窗格里的Agent模型能力和输出长度就和其他窗格不一样适合承担轻量任务。顺手提一句这些变量的精确名称在不同版本里会有变化建议跑一下claude --help确认当前版本支持哪些。再说MCP。MCP是Agent连接外部工具的协议Claude Code可以挂数据库查询工具、浏览器工具、文件搜索工具等。MCP配置有两个层级~/.claude/settings.json是全局的所有Agent都会加载.claude/settings.json是项目级的只有在这个目录下启动的Agent才加载。我的原则是把所有Agent都要用的通用工具放全局把特定业务的工具放项目级。比如全局只挂一个通用的文件搜索和代码检索项目级才挂数据库查询、API调试这类有业务属性的工具。这样既能避免每个Agent启动时加载一堆用不上的工具拖慢速度也能防止Agent误用不属于当前任务的工具权限。5. 总管落地从一条命令启动到一键切换5.1 先手动搭一遍再固化成脚本配置层面的事捋顺了接下来就是把整套流程固化成“一键启动”。我不建议一上来就上tmuxinator这类自动化工具新手容易懵。先把手动流程跑通找到自己最顺手的布局再考虑固化。我的标准启动流程分四步第一步创建总sessiontmux new -s agent-ctrl第二步创建三个window并命名自动进入工作目录# 默认第一个window重命名为 backend 并进入目录 tmux rename-window backend cd ~/work/order-backend # 新建第二个window命名为 frontend tmux new-window -n frontend cd ~/work/order-frontend # 新建第三个window命名为 review tmux new-window -n review cd ~/work/code-review第三步在需要的window里做横向/纵向切分。比如frontend这个window我习惯左半边跑Claude Code右半边跑dev servertmux select-window -t agent-ctrl:frontend tmux split-window -h # 纵向切分左右两个pane第四步在每个窗格里手动启动claude或者需要跑的命令。这套手动流程熟练之后你会发现每次要敲的命令挺多。这时候就该上脚本了。我写了一个简单的bash脚本放在~/bin/agent-ctrl里内容大致是这样#!/usr/bin/env bash SESSIONagent-ctrl # 如果session已存在直接attach进去避免重复创建 if tmux has-session -t $SESSION 2/dev/null; then tmux attach -t $SESSION exit 0 fi tmux new-session -d -s $SESSION -n backend -c ~/work/order-backend tmux new-window -t $SESSION -n frontend -c ~/work/order-frontend tmux new-window -t $SESSION -n review -c ~/work/code-review # 在frontend window里纵向切分左侧claude右侧dev server tmux select-window -t $SESSION:frontend tmux split-window -h -c ~/work/order-frontend tmux select-pane -t 0 tmux send-keys -t $SESSION:frontend.0 claude Enter tmux select-window -t $SESSION:backend tmux send-keys -t $SESSION:backend.0 claude Enter tmux select-window -t $SESSION:review tmux send-keys -t $SESSION:review.0 claude Enter tmux attach -t $SESSION注意脚本里有个细节tmux has-session判断session是否已经存在如果存在就直接attach。很多人的脚本没有这一步重复执行会创建一堆重名session越搞越乱。这个判断是“总管”脚本里很值得抄的一个点。5.2 用tmuxinator管理更复杂的布局如果你的Agent任务线更多比如五个窗口、每个窗口里还要跑两三个pane、每个pane要执行不同的初始命令纯bash脚本会越来越难维护。这时候我推荐tmuxinator。tmuxinator用YAML文件描述布局一个文件就是一套完整方案。安装gem install tmuxinator然后在~/.config/tmuxinator/agent-ctrl.yml里写name: agent-ctrl root: ~/ windows: - backend: root: ~/work/order-backend panes: - claude - tail -f /tmp/order-service.log - frontend: root: ~/work/order-frontend layout: main-horizontal panes: - claude - npm run dev - review: root: ~/work/code-review panes: - claude - echo read-only workspace启动就一行命令tmuxinator start agent-ctrl写YAML时最容易出错的是缩进问题YAML对缩进敏感。我建议写完先跑tmuxinator doctor检查一下配置再实际启动能省不少时间。5.3 交互Agent和批量Agent分开管还有一个我强烈推荐给“总管”加上的能力区分交互式Agent和批量式Agent。Claude Code支持非交互模式claude -p也就是直接给一段提示词Agent跑完就退出。这个模式特别适合批量任务比如批量给多个文件生成单元测试、批量重构命名、批量检查代码规范问题。跑这种任务不需要占一个交互窗格完全可以放进后台跑输出重定向到日志文件。我的做法是在tmux里专门留一个tasks窗口里面不放交互Agent而是跑批量任务。例如cd ~/work/order-backend claude -p 给 src/service 目录下所有 go 文件生成表驱动单元测试测试文件写到对应目录不要改动源码 /tmp/agent-tasks/test-gen.log 21 这样批量任务在后台跑日志实时写入文件我随时可以tail -f看进度。同时交互Agent们在其他窗格里正常干活互不占用。等批量任务跑完再切到tasks窗口看结果。这里有个经验批量任务最好通过--allowedTools参数限制Agent的权限比如只允许Write和Edit不允许Bash执行命令防止Agent在没人盯着的时候做出危险操作。6. 常见问题与排查技巧实录6.1 问题速查表这套方案我用了大半年踩过的坑整理成了一张速查表按频率排的现象原因解决方案多个Claude Code互相“串味”任务上下文混乱多个Agent共用同一工作目录CLAUDE.md互相干扰每个Agent独立工作目录严格按项目写入CLAUDE.mdtmux会话里的Claude Code在电脑休眠后假死终端进程挂起需要唤醒刷新Ctrlb后按r重载窗口或重新attach会话前端和后端Agent的dev server端口冲突两个Agent在各自容器/进程里同时监听同端口给不同Agent预设不同环境变量PORT3001、PORT3002分别启动tmux里复制粘贴行为怪异tmux有自己的复制缓冲区和剪贴板系统鼠标开启模式下选中即复制配合Shift鼠标选中走系统剪贴板Claude Code在tmux里提示登录失效会话切换导致登录态检查重新触发重新执行一次登录流程即可会话历史不受影响一个窗格里跑多个claude实例看不出谁是谁窗格标题显示的是claude无法区分任务用pane-border-format显示窗格序号或用不同颜色的tmux状态配置区分6.2 几个容易忽视的细节除了上面这些还有几个细节在长跑中特别重要。第一妥善命名你的会话和窗口。我见过太多人跑起来一堆tmux窗口全叫默认名字最后自己也分不清。养成习惯每个Agent任务开始前重命名window最好用业务名而不是“1”“2”“3”。这个习惯在Agent数量超过三个的时候节省的时间远比你想象的要多。第二注意环境变量隔离。tmux里的不同window默认继承同一套环境变量。如果你在一个窗格里改了ANTHROPIC_MODEL其他窗格不受影响因为环境变量是在进程启动时确定的。但如果你用的是shell启动文件里全局设置的环境变量所有Agent都会读到一个模子里刻出来的配置。所以我的建议是跟特定Agent绑定的环境变量要在启动这个Agent之前临时设置或者写进该项目的启动脚本里而不是放在~/.bashrc里全局导出。第三个人体验中最有价值的一条在CLAUDE.md里千万别放密钥、token、数据库密码。因为同一目录下的所有Agent都能读到一旦你的Agent被诱导输出文件内容等同直接泄露。密钥只通过环境变量传给需要的Agent进程这是底线。6.3 如果Agent卡死或者跑飞了怎么办终端里跑多个Agent难免撞上“跑飞”的情况——Agent进入死循环、不断执行同一条命令、或者开始改不该改的文件。我的止损流程是先看窗格状态。如果Agent还在正常运行只是逻辑不对用Ctrlc中断当前输出在会话里输入“停下来重新审视你刚才的计划”。如果Agent在疯狂执行命令直接关掉对应窗格:tmux kill-pane -t 窗格编号把这个Agent彻底杀掉从备份/新目录重新拉起一个干净会话。这里有个技巧重要任务一定要用Claude Code的分支机制在动手改代码前先fork一个会话原会话保留。这样即使新路线的Agent跑飞了随时可以回到原会话不会把整个任务线搞死。7. 一个值得长期投入的方向这套多Agent管理方案短期内解决的是“终端里同时跑几个Claude Code”的具体问题但长期看它其实是你Agent协作能力的基本功。当你习惯了用tmux管理Agent、用CLAUDE.md定义Agent角色、用环境变量和MCP区分Agent权限之后你会发现“多个Agent协作”这件事不再是一个抽象概念而是一件可以随时调整、随时扩展的日常操作。今天可能是Claude Code管前端、另一个管后端明天可能是三个Agent分别写文档、写测试、做审查后天可能其中一个Agent换成Codex甚至换成其他支持终端操作的Agent工具。配置方法大同小异底层逻辑都是同一套控制好终端进程的存活、控制好会话上下文的隔离、控制好Agent的权限边界。这三板斧握在手里你的终端就是一支可以随时扩充的AI团队。