剪贴板包装

为什么有 wrap

程序里的复制常常是 OSC 52 转义：进程打印一段特殊序列，有能力的终端把解码后的文本放到剪贴板。Apple Terminal 不实现 OSC 52。嵌套的 tmux、SSH、docker exec 和 kubectl exec 也可能吞掉这段序列，或永远送不到外层终端。

matcha wrap 坐在**你和命令之间**。它分配一个本地伪终端，在那里跑你的命令，监视输出里的 OSC 52（普通的和 tmux 包装的），并把文本写到**本地操作系统剪贴板**。外层终端不必懂 OSC 52。

wrap 做什么

matcha wrap docker exec -it my-container bash
matcha wrap kubectl exec -it my-pod -- bash
matcha wrap ssh user@host

• 把子命令的输出转到屏幕（已消费的 OSC 52 除外）
• 把内层终端尺寸与窗口同步（Unix；Windows ConPTY 不转发实时缩放）
• 被包装的进程带着未恢复的终端模式死去时，帮你恢复（掉线的 SSH、SIGTERM）
• 在 Unix 上，单条加引号的命令行，或只是 shell 别名的名字，会经 $SHELL -i -c 运行，以便别名和分词生效

Matcha 自己的 TUI 也可以发出 OSC 52。那是与 wrap 分开的路径。MATCHA_CLIPBOARD_NO_OSC52=1 关掉 Matcha 的发出；它不会阻止 wrap 拦截子进程的序列。

什么时候用

需要在容器、pod 或 SSH 主机**里面**开 shell，且那个程序里的复制应粘贴到本地时用 wrap — 尤其是 Apple Terminal，或 /doctor 报告 OSC 52 不受支持或未验证时。

如果已经不经 wrap 直接 SSH 进去，Matcha 可能一次性提示你用 wrap。/doctor 可以提供 matcha doctor fix ssh-wrap（给你的 shell 加别名）。这条提示不会盖住 Doctor 的建议。在 /settings → **Show contextual hints** → **SSH wrap** 关掉提示，或在 $MATCHA_HOME/config.toml 的 [ui.contextual_hints] 下设 ssh_wrap = false。

跑 wrap

在**本地**机器上，给本来要打的命令加上前缀：

matcha wrap ssh user@host
matcha wrap docker exec -it my-container bash
matcha wrap kubectl exec -it my-pod -- bash

加引号的单行命令（Unix）会经过你的 shell：

matcha wrap "ssh user@host"

然后在内层程序里照常复制。序列会被消费；屏幕上不应看到 Base64 团。在本地机器上粘贴。

若 PTY 建立失败，wrap 会打印警告，并**不**转发剪贴板地跑命令，以便会话仍能开始。

先用 matcha doctor 或 /doctor 诊断。看 Clipboard 一节：**native**、**tmux** 和 **OSC 52**。wrap 生效后，Doctor 可以把 OSC 52 sink 显示为 on。