关于 wezterm
wezterm 是面向高内存环境中 Agent 集群的 WezTerm 配置与运维指南，适合同时运行多个编码 Agent 的用户。它涵盖性能调优、持久会话、远程复用、故障排查和会话救援。
主要功能
- 01按内存调整缓冲区与缓存
- 02管理 WezTerm mux 会话和窗格
- 03配置远程持久会话
- 04使用 reptyr 救援运行中的会话
- 05排查性能与连接问题
适用场景
- 01并行运行多个编码 Agent
- 02调优高输出量终端会话
- 03通过 SSH 管理远程 mux 会话
- 04mux 无响应时尝试迁移会话
安装
复制下面的命令，在终端中运行。
$
npx skills add https:/安装后在 Claude Code 中输入/wezterm确认已加载。
包含的文件
除 SKILL.md 外，安装时一起下载的参考资料和脚本。
references/COMMANDS.mdPERFORMANCE-TUNING.mdPERSISTENT-SESSIONS.md详细介绍
WezTerm — 高内存 Agent 群管理
核心原则： WezTerm mux 替代 tmux。利用海量内存（512GB+）运行 Agent 群。绝不嵌套复用器。
快速诊断
# One-liner status
echo "Mux: $(ps aux | grep -c '[w]ezterm-mux') procs | $(wezterm cli list --format json 2>/dev/null | jq length) panes | RSS: $(ps -eo rss,args | grep '[w]ezterm-mux' | awk '{sum+=$1} END {printf "%.1fGB", sum/1024/1024}')"
# Is mux running?
ps aux | grep wezterm-mux | grep -v grep
# Memory usage
ps -eo pid,rss,args | grep wezterm-mux | awk '{printf "%.1fGB\n", $2/1024/1024}'
# Recent logs
tail -20 /run/user/$(id -u)/wezterm/wezterm-mux-server-log-*.txt
# Connection test
wezterm cli list --format json | jq length
# Socket status
ls -la /run/user/$(id -u)/wezterm/sock
Agent 群问题
运行 20+ 个 AI Agent（Claude Code、Codex、Gemini CLI）时，每个 Agent 都会持续输出、运行数小时、启动子进程并行工作。这会超出 WezTerm 默认设置的承载能力。
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ THE FAILURE CASCADE ┃
┃ ┃
┃ 1. Output buffer fills → parser falls behind ┃
┃ 2. Coalesce delay accumulates → lag builds up ┃
┃ 3. Caches thrash → CPU spikes on render ┃
┃ 4. Socket buffers fill → connection hangs ┃
┃ 5. You restart mux → ALL SESSIONS DIE (use reptyr first!) ┃
┃ ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
默认假设与现实
| WezTerm 的假设 | Agent 群运行时的实际情况 |
|---|---|
| 约 100 行/秒 | 所有窗格合计每秒 1,000+ 行 |
| 偶尔访问回滚记录 | 回滚记录是主要调试工具 |
| 窗格较少 | 20+ 个窗格，且全部处于活动状态 |
| 缓存命中很常见 | 上下文快速切换 = 缓存未命中 |
性能调优（高内存）
精确提示词 — 根据内存自动调优
# Auto-tune using linear interpolation (recommended)
curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/misc_coding_agent_tips_and_scripts/main/wezterm-mux-tune.sh | bash
# Preview without applying
./wezterm-mux-tune.sh --dry-run
# Calculate for specific RAM
./wezterm-mux-tune.sh --ram 200
# Use exact fixed profile
./wezterm-mux-tune.sh --profile 512
# Restore from backup
./wezterm-mux-tune.sh --restore
精确提示词 — 512GB 手动配置
在 return config 之前添加到 ~/.wezterm.lua：
-- 512GB HIGH-RAM PROFILE
config.scrollback_lines = 10000000
config.mux_output_parser_buffer_size = 16 * 1024 * 1024
config.mux_output_parser_coalesce_delay_ms = 1
config.ratelimit_mux_line_prefetches_per_second = 1000
config.shape_cache_size = 65536
config.line_state_cache_size = 65536
config.line_quad_cache_size = 65536
config.line_to_ele_shape_cache_size = 65536
config.glyph_cache_image_cache_size = 4096
设置速查
| 设置 | 默认值 | 512GB | 用途 |
|---|---|---|---|
scrollback_lines | 3,500 | 10M | 每个窗格的历史记录 |
mux_output_parser_buffer_size | 128KB | 16MB | PTY 批处理缓冲区 |
mux_output_parser_coalesce_delay_ms | 3 | 1 | 解析延迟 |
ratelimit_mux_line_prefetches_per_second | 50 | 1000 | 滚动速度 |
shape_cache_size | 1,024 | 65,536 | 字体缓存 |
line_state_cache_size | 1,024 | 65,536 | 行属性缓存 |
line_quad_cache_size | 1,024 | 65,536 | GPU 几何数据 |
glyph_cache_image_cache_size | 256 | 4,096 | 光栅化字形 |
按内存配置
| 内存 | scrollback | buffer | caches | prefetch | 内存占用 |
|---|---|---|---|---|---|
| 64GB | 1M | 2MB | 8K | 500 | 3-8 GB |
| 128GB | 2M | 4MB | 16K | 750 | 5-15 GB |
| 256GB | 5M | 8MB | 32K | 500 | 8-25 GB |
| 512GB | 10M | 16MB | 64K | 1000 | 15-60 GB |
应用后： 重启 mux 以加载新设置。
紧急会话抢救
场景： Mux 无响应，但 Agent 仍在运行。先别杀掉 mux！
精确提示词 — reptyr 抢救工作流
# 1. Connect via plain SSH (bypass broken mux)
ssh user@host
# 2. Setup
sudo apt-get install -y reptyr
sudo sysctl -w kernel.yama.ptrace_scope=0
# 3. Create rescue session
tmux new-session -d -s rescue -x 200 -y 50
# 4. Find agents
ps -eo pid,args | grep -E 'claude --dangerously|codex --dangerously' | grep -v grep
# 5. Migrate each agent
for pid in $(ps -eo pid,args | grep -E 'claude --dangerously|codex --dangerously' | grep -v grep | awk '{print $1}'); do
tmux new-window -t rescue -n "agent-$pid"
tmux send-keys -t "rescue:agent-$pid" "reptyr -T $pid" Enter
sleep 0.5
done
# 6. Verify migrations
for win in $(tmux list-windows -t rescue -F "#{window_name}" | grep agent); do
tmux capture-pane -t "rescue:$win" -p | grep -qE "bypass|Claude" && echo "✓ $win" || echo "✗ $win"
done
# 7. NOW safe to kill mux
pkill -9 -f wezterm-mux
# 8. Restore security
sudo sysctl -w kernel.yama.ptrace_scope=1
# 9. Restart mux
wezterm-mux-server --daemonize
# 10. Access rescued agents
tmux attach -t rescue # Ctrl-b w to browse
reptyr 故障模式
| 错误 | 原因 | 修复方法 |
|---|---|---|
| "Operation not permitted" | ptrace 被阻止 | sudo sysctl -w kernel.yama.ptrace_scope=0 |
| "shares process group" | 进程有子进程 | 使用 reptyr -T（不要只用 reptyr） |
| "Unable to attach" | 存在额外保护 | 无法迁移；会话将丢失 |
成功率： 50-70%。与正在运行且有许多子进程的会话相比，较旧或空闲的会话更容易迁移。
Mux 服务操作
启动/停止
# Start (daemonized)
wezterm-mux-server --daemonize
# Stop gracefully
pkill -f wezterm-mux-server
# Force stop (kills sessions!)
pkill -9 -f wezterm-mux-server
# Restart (loses sessions unless rescued first)
pkill -9 -f wezterm-mux; wezterm-mux-server --daemonize
# Restart via systemd (if configured)
systemctl --user restart wezterm-mux-server
杀掉卡住的代理进程
可以安全杀掉，不会影响 mux 会话：
pkill -f 'wezterm cli.*proxy'
Mux 性能随时间下降的原因
| 原因 | 症状 | 修复方法 |
|---|---|---|
| 缓冲区溢出 | 连接超时 | 增大 mux_output_parser_buffer_size |
| 缓存抖动 | 滚动时 CPU 占用高 | 增大缓存大小 |
| 会话累积 | 内存膨胀 | 定期重启 mux |
| 回滚记录堆积 | 占用数 GB 内存 | 降低 scrollback_lines 或重启 |
持久会话设置
远程服务（一次性设置）
mkdir -p ~/.config/systemd/user
cat > ~/.config/systemd/user/wezterm-mux-server.service << 'EOF'
[Unit]
Description=WezTerm Mux Server
After=network.target
[Service]
Type=simple
ExecStart=/usr/bin/wezterm-mux-server --daemonize=false
Restart=on-failure
RestartSec=5
Environment=WEZTERM_LOG=warn
[Install]
WantedBy=default.target
EOF
systemctl --user daemon-reload
systemctl --user enable --now wezterm-mux-server
sudo loginctl enable-linger $USER
本地配置（SSH 域）
config.ssh_domains = {
{
name = 'myserver',
remote_address = '10.0.0.1',
username = 'ubuntu',
multiplexing = 'WezTerm', -- Key setting
assume_shell = 'Posix',
},
}
CLI 速查
| 任务 | 命令 |
|---|---|
| 列出窗格 | wezterm cli list |
| 列出窗格（JSON） | wezterm cli list --format json |
| 向右拆分 | wezterm cli split-pane --right |
| 向下拆分 | wezterm cli split-pane --bottom |
| 发送文本 | wezterm cli send-text --pane-id N "cmd\n" |
| 新建标签页 | wezterm cli spawn |
| 在域中创建新标签页 | wezterm cli spawn --domain-name SSH:host |
| 连接到 mux | wezterm connect unix |
| 切换缩放 | wezterm cli zoom-pane --toggle |
维护清单
- 每周： 检查 mux 内存；如果 RSS > 50GB，考虑重启
- 重启前： 检查是否有活动 Agent（如有需要，使用 reptyr）
- 调整设置后： 重启 mux 以应用新设置
- 版本不匹配： 客户端和服务端的版本必须完全一致
# Check version match
wezterm --version # local
ssh host 'wezterm --version' # remote
# Check mux memory
ps -eo rss,args | grep '[w]ezterm-mux' | awk '{printf "RSS: %.1fGB\n", $1/1024/1024}'
故障排查
| 症状 | 原因 | 解决方法 |
|---|---|---|
| 连接超时 | 缓冲区溢出 | 增大 mux_output_parser_buffer_size |
| 滚动卡顿 | 预取速率低 | 增大 ratelimit_mux_line_prefetches_per_second |
| 渲染时 CPU 占用率高 | 缓存抖动 | 增大所有缓存大小 |
| 历史记录被截断 | 回滚缓冲区过小 | 增大 scrollback_lines |
| 日志中出现 “Broken pipe” | 客户端断开连接 | 检查网络稳定性 |
| “Checking server version” 卡住 | Mux 过载 | 恢复会话，然后重启 mux |
| 版本不匹配错误 | 客户端和服务端版本不同 | 将两者更新到相同版本 |
日志位置
# Mux server log
/run/user/$(id -u)/wezterm/wezterm-mux-server-log-*.txt
# Socket path
/run/user/$(id -u)/wezterm/sock
参考资料
| 主题 | 文件 |
|---|---|
| 完整的 CLI 命令 | COMMANDS.md |
| 持久会话深入介绍 | PERSISTENT-SESSIONS.md |
| 性能调优深入介绍 | PERFORMANCE-TUNING.md |
评论
支持 Markdown