在 Warp + tmux 下使用 Claude Code：一次剪贴板踩坑记录
环境：macOS + Warp Terminal + tmux + Claude Code
起因
最近把主力终端换成了 Warp，用下来体验不错——AI 补全、命令分组、界面好看。但有一个习惯一直没改：重度依赖 tmux 管理会话。
同时，我也开始频繁使用 Claude Code 辅助写代码。三者叠在一起，问题来了。
症状
某天我在 tmux session 里启动 Claude Code，想把终端里的一段报错信息复制进去让它分析。Cmd+C 复制，切到 Claude Code 输入框，Cmd+V——
什么都没有。
输入框纹丝不动。
以为是偶发，重试几次，还是不行。换成手动重新输入，能用，但几十行的报错显然不可能手打。
排查过程
第一反应：怀疑 Claude Code 的问题
去翻了一下 Claude Code 的 issue，发现有类似反馈，但没有定论。先排除。
转向怀疑 Warp
Warp 本身对 Cmd+V 有自己的处理逻辑，会走系统剪贴板。在 Warp 原生 pane（没有 tmux）里测试，Claude Code 的输入框粘贴完全正常。
问题范围缩小：tmux 里才会出现。
锁定 tmux 的剪贴板机制
tmux 有自己独立的 paste buffer，和系统剪贴板（macOS 的 pbpaste/pbcopy）是两套东西。
在 tmux 内，Cmd+V 这个动作经过的路径大概是：
系统剪贴板 → Warp 拦截 → tmux pty 层 → 应用输入框
中间任何一层处理不对，内容就丢了或者发不进去。
Claude Code 用 Ink（React for CLI）渲染 TUI，输入框的事件处理和普通 shell prompt 不同，对这条链路更敏感。
解决过程
尝试一：Ctrl+B ]（tmux 原生粘贴）
tmux 有自己的粘贴命令，但这走的是 tmux buffer，不是系统剪贴板，复制过来的内容根本不在这个 buffer 里，无效。
尝试二：set-clipboard on
# ~/.tmux.conf
set -g set-clipboard on
重启 tmux，没有改善。
尝试三：reattach-to-user-namespace（有效 ✅）
这是 macOS 下 tmux 剪贴板问题的经典解法。tmux 在 macOS 上启动时，用户命名空间和系统剪贴板访问会脱节，这个工具把它们重新连起来。
brew install reattach-to-user-namespace
然后在 ~/.tmux.conf 加：
set -g default-command "reattach-to-user-namespace -l zsh"
tmux kill-server 重启，重新进入 session，再试——粘贴成功了。
最终配置
把几个相关配置一起整理进 ~/.tmux.conf：
# 终端类型
set -g default-terminal "xterm-256color"
set -ag terminal-overrides ",xterm-256color:RGB"
# 让 Warp 的转义序列能穿透 tmux（对 TUI 应用很重要）
set -g allow-passthrough on
# macOS 剪贴板修复
set -g default-command "reattach-to-user-namespace -l zsh"
# 同步 copy-mode 到系统剪贴板
bind-key -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "pbcopy"
bind-key -T copy-mode MouseDragEnd1Pane send-keys -X copy-pipe-and-cancel "pbcopy"
根本原因回顾
| 层级 | 问题 |
|---|---|
| macOS + tmux | tmux 启动时脱离用户命名空间，无法访问系统剪贴板 |
| Warp + tmux | Warp 的输入处理与 tmux pty 层有摩擦 |
| Claude Code + tmux | Ink TUI 对输入事件链路更敏感，普通 shell 不明显的问题在这里放大 |
三个因素叠加，才让这个问题这么难察觉——单独用其中任意两个都不会稳定复现。
如果你不想改配置
最简单的临时方案：直接在 Warp 原生 pane 里跑 Claude Code，不套 tmux。
Warp 自带分屏（Cmd+D / Cmd+Shift+D）和多 Tab，日常用够了。tmux 留给 SSH 远程场景。
小结
这种问题的麻烦之处在于，单独看每个工具都没有 bug，是组合使用时的边界条件。排查时要一层一层剥：先定位是哪两个工具的组合出了问题，再找对应的修复。
reattach-to-user-namespace 解决了我的问题，希望也能帮到同样踩坑的人。
另外这个问题在iTerm2中是不存在的，如果要配合tmux的场景比较多，可以尝试使用iTerm2。
