我把 Codex 接进 SSH 后，才发现 Xterminal MCP 最难的是敢不敢让 Agent 动手

值班时最容易被低估的请求是："帮我看一下这台服务器最近的错误日志，整理成一条排障笔记。"把 Xterminal 接上 Codex 或 Claude Code 后，客户端很快就能列出工具，仿佛只差一句自然语言。真正卡住的却是下一步：Agent 能不能看到这台服务器，日志要落到哪个本地目录，写笔记是否需要确认，万一它顺手调用 sudo 谁来拦住？

这个场景很适合检验 MCP 的价值，也很容易暴露配置漏洞。一个 AI Agent 请求可能同时经过 SSH 命令、远程文件、本地目录和工作区写入；把 Xterminal 当作 SSH MCP 接入层时，只要其中一层范围过宽，确认窗口就会变成临时补救。我把这次"查日志并留痕"拆成一条可复现的接入路径，重点看 Xterminal 怎样让 Agent 找到授权的 SSH 连接，哪些地方减少重复劳动，哪些地方必须保留人工停顿。

先弄清楚 Agent 连的是哪一台设备

Xterminal 提供的是本机 MCP 服务，Codex 或 Claude Code 连接运行 Xterminal 的那台电脑，而不是直接把 MCP 暴露到远程服务器。默认监听 127.0.0.1:12335，端点是：

text 复制代码

http://127.0.0.1:12335/mcp

这意味着 Agent 的远程命令仍然要经过 Xterminal 中已经配置好的 SSH 连接。MCP 不会替你创建一条绕过连接中心的通道，也不会把保存的私钥或密码返回给客户端。它更像一个受控中转层：外部客户端提出请求，Xterminal 根据自己的连接、范围和策略决定能不能继续。

如果 Codex 运行在 WSL 或其他受控环境，才可能需要把监听地址改成 0.0.0.0 或可达的内网地址。这里的变化会扩大服务暴露面，并不只是让连接更稳定。改完之后，令牌、服务器范围、本地目录和网络层访问控制都要一起收紧；只改监听地址而不补其他限制，等于把侧门搬到了更大的走廊上。

端口被占用时 MCP 会启动失败，不会自动换端口。遇到 Agent 连不上，我会先在 Xterminal 中确认服务状态、监听地址和端口，再回到客户端检查端点是否包含 /mcp，而不是先重建令牌。

工具开关决定 Agent 能拿到哪类能力

MCP 设置中的工具按工作区、SSH、远程文件和文件传输分组。工作区工具可以浏览或修改连接、分组、快速命令和笔记；SSH 工具可以列出已暴露的服务器并执行普通命令或 sudo；远程文件工具负责目录、文本和元数据；文件传输工具负责上传、下载、查看状态和取消任务。

这些开关对所有 MCP 客户端生效。关闭一组工具后，已经连接的 Agent 需要重新连接才能刷新工具定义。这里有个容易被忽略的后果：你在 Xterminal 里关了一个按钮，不代表外部客户端立刻忘记了旧列表。重新连接既是刷新能力，也是确认限制真正传到 Agent 的证据。

我会先只保留当前任务需要的最小组。例如只想让 Agent 查看远程日志，就不必同时开启文件传输和工作区写入。工具开关做的是"能力类别"限制，不能代替具体服务器和目录的访问范围；两层都收窄，确认窗口里的目标才会清楚。

让 Agent 只看到指定 SSH 和本地目录

在访问范围中，SSH 服务器可以选择全部或指定连接，本地目录也可以选择全部或指定路径。官方建议优先使用指定服务器。Agent 需要先调用 xterminal_ssh_list_servers 获取已暴露连接，再用返回的服务器 ID 发起命令或文件操作，这一步把"找到目标"和"执行动作"分开了。

本地目录限制同样重要。指定目录按真实路径边界检查，不能用 .. 或符号链接绕过；上传源文件和下载目标都会受到限制。假设任务只是把日志下载到项目的 tmp/ai-review，我不会为了省一次配置把整个用户目录暴露给 MCP。范围越小，Agent 的每次请求越容易被人读懂。

一个反例是先选"全部服务器"，等出问题再收窄。这样做不仅风险更高，也会让排障变复杂：当 Agent 读到不相关的服务器时，你很难判断是模型扩展了问题，还是权限本来就给得过宽。指定范围后，新增的 SSH 连接也不会自动获得权限；找不到服务器时先检查访问范围，不要直接重建客户端。

从列服务器到执行命令，Agent 的接入链路

在"查日志"的实际流程里，Agent 不会凭空猜服务器名称，它先走工具链：调用 xterminal_ssh_list_servers，回读名称、地址和分组，再把返回的 serverId 交给 xterminal_ssh_exec。如果要读取文本，则继续核对远程路径；要下载文件，则把本地目标固定在已允许目录中。

我会让 Agent 先执行只读命令，例如查看日志目录中的文件名、修改时间和大小，然后再决定是否读取内容。每一步都回读退出码、标准输出、标准错误和耗时。这样的顺序看起来比一句"帮我排查"慢，却能留下服务器 ID、命令和结果，方便把笔记交给下一位值班同事。

Codex 的配置可以保持占位符，不要把真实令牌写进文章或仓库：

toml 复制代码

[mcp_servers.xterminal]
url = "http://127.0.0.1:12335/mcp"
http_headers = { Authorization = "Bearer <MCP_TOKEN>" }
default_tools_approval_mode = "prompt"
tool_timeout_sec = 120

default_tools_approval_mode = "prompt" 很适合第一次接入，因为它把请求停在 Xterminal 的确认窗口里。Agent 负责把步骤串起来，Xterminal 负责把每一步限制在授权范围内，这正是 MCP 比"复制一条 SSH 命令给 AI"更有价值的地方。

普通命令、sudo 和工作区写入要分开设防

普通 SSH 命令和远程文件操作由命令执行策略控制，可以设为"每次确认"或"直接执行"。每次确认时，Xterminal 会显示请求客户端、目标服务器、操作类型、命令、工作目录和文件路径；覆盖文件还会显示警告。窗口超时或被关闭，请求会被拒绝。

sudo 有独立的"禁用、每次确认、直接执行"策略，还要求客户端令牌单独开启"允许 sudo"。只有全局策略和令牌权限都放行，Agent 才可能使用 sudo 工具。执行 xterminal_ssh_sudo_exec 时不需要把 sudo 写进参数，Xterminal 会在授权后处理提权，密码也不应该由客户端塞进命令行。

工作区管理又是另一条链。设置为"写入时确认"时，Agent 可以浏览目录信息，但创建或修改连接、快速命令和笔记前会显示字段预览，并隐藏保存的密码值。我让 Agent 写排障结论时，会先回读笔记标题和分类，确认对象 ID，再批准保存，而不是赋予整个工作区的直接写入权。

令牌是 Agent 的门票，不是 Xterminal 凭据的副本

为 Codex 或 Claude Code 创建客户端时，Xterminal 生成 Bearer 令牌。令牌只在创建弹窗中显示一次，列表里只保留摘要和权限状态。令牌不能提交到代码仓库、聊天记录或截图中；怀疑泄露时，先撤销旧令牌，再重新创建客户端配置。

令牌可以分别控制是否允许 sudo、是否允许工作区管理，但这两项权限仍受服务器范围和执行策略约束。MCP 也不会通过工具返回已经保存的私钥、密码、私钥密码或 SSH 代理凭据，所以 Agent 不能靠列工具"读出"现有登录秘密。

如果工具配置改过，重新连接 Agent 让工具列表更新。只看聊天窗口里的旧工具名，不足以证明新策略已生效；Xterminal 的运行状态、客户端连接状态和一次真实的只读请求，才是更可靠的回读证据。

哪些任务不该交给 MCP

MCP 适合把"查、读、整理"串起来，不适合硬塞需要交互式终端、动态验证码、持续运行程序或人工输入密码的任务。大文件或长时间传输应通过传输状态工具跟踪，不要因为 Agent 没有立刻返回就重复提交同一任务。

它也不能替代服务器权限、审计系统和发布流程。云端保存仍受登录状态和 Pro 权限检查，启用 MCP 不会绕过这些条件。监听地址扩大后，网络层的来源控制仍由用户负责，令牌也需要像其他访问凭据一样轮换和撤销。

如果请求一直等待，先看 Xterminal 窗口是否仍在运行、确认弹窗是否被挡住，再检查普通命令、SFTP、工作区写入和令牌权限分别是哪一层拒绝。把所有失败都归因于网络，会错过最有价值的证据。

还有一个容易忽略的现场细节：Agent 可能已经拿到上一次请求的工具结果，却因为用户迟迟没有点确认而继续等待。这个状态不代表远程命令正在后台运行。确认窗口超时或被关闭后，请求会被拒绝；我会把拒绝当成一次完整的失败记录，重新发起前先确认没有重复的传输任务或同名文件写入。

如果工具列表里没有 xterminal_ssh_list_servers，先回到工具开关和客户端重连；如果能列出服务器却没有目标连接，检查访问范围；如果目标存在但执行被挡住，再看普通命令策略和令牌权限。这个分层顺序能把"Agent 不会用"拆成三个更具体的问题，也能避免为了让请求通过而把全部能力一次性打开。

在团队交接里，我还会记录本次接入使用的监听地址、暴露的服务器、允许的本地目录、令牌摘要和确认策略。记录不包含令牌本身，只说明它由谁创建、什么时候撤销。下一位同事看到同样的任务时，可以复用边界，而不是复制一份未知来源的客户端配置。

这种记录也方便回收权限。临时排障结束后，撤掉不再需要的服务器和目录，必要时直接撤销客户端令牌。MCP 配置不是一次完成就永久不变的清单，任务边界变化时，访问范围也应该跟着变化。

我会怎样判断 Xterminal MCP 值不值得开

当任务需要让 Agent 在有限的服务器和目录里反复查状态、读文件、整理结果，Xterminal MCP 能减少复制粘贴和上下文切换；当任务是一次性的交互式操作，直接使用 SSH 终端通常更清楚。我更关心每个请求能不能在确认窗口里说清楚目标、动作和后果，工具数量反而排在后面。

Xterminal 的优势在于把连接、SFTP、工作区和确认策略放在同一个边界内；限制也很具体：监听地址改大后要承担暴露面，直接执行会减少人工停顿，指定范围需要持续维护，客户端配置还要保管好令牌。把这些代价写进启用记录，MCP 才会从"Agent 能连上"变成一条可复盘的 SSH 工作路径。

回到值班时那句"帮我看日志"，我不会先问 Agent 能不能替我执行命令，而会先问它最多能看到哪台服务器、哪一个目录，哪一步必须由我确认。边界说清楚之后，MCP 才真正有用；边界说不清楚，连通本身反而是最不值得庆祝的结果。