exec 工具

exec 工具让 Agent 在工作区执行 Shell 命令，支持前台同步执行和后台异步执行，配合 process 工具管理后台进程。

参数说明

参数	说明	默认值
command	要执行的命令（必填）	—
workdir	工作目录	当前 cwd
env	环境变量覆盖（key/value）	—
yieldMs	超时后自动转为后台	10000ms
background	立即后台执行	false
timeout	超时后强制终止（秒）	1800
pty	使用伪终端（TTY 交互程序用）	false
host	执行位置：sandbox、gateway、node	sandbox
security	安全模式：deny、allowlist、full	allowlist（gateway/node）
ask	审批提示：off、on-miss、always	on-miss
node	指定 node 节点 id/名称（host=node 时用）	—
elevated	请求提升权限（沙箱内运行时有效）	false

执行位置说明

• sandbox（默认）：在隔离容器内运行，安全性最高。注意：沙箱需显式启用，否则 host=sandbox 会失败报错。
• gateway：在 Gateway 宿主进程上直接运行，需通过审批列表。
• node：在配对的 macOS 节点（伴生 App 或无头 Node Host）上运行。

前台与后台执行

前台执行（等待命令完成）：

{ "tool": "exec", "command": "ls -la" }

后台执行 + 查询状态（命令较慢时使用）：

{"tool":"exec","command":"npm run build","yieldMs":1000}
{"tool":"process","action":"poll","sessionId":"<id>"}

当命令后台运行时，exec 返回 status: "running" 和 sessionId，然后用 process 工具进行：

• poll：获取新输出和退出状态
• log：按行读取输出（支持 offset/limit）
• write：向标准输入写数据
• kill：终止进程
• clear/remove：清理记录

PTY（伪终端）模式

对于需要真实终端的程序（如 ncurses TUI、claude-code、交互式 REPL），使用 pty: true：

{ "tool": "exec", "command": "python -i", "pty": true }

配合 process 工具发送按键：

{"tool":"process","action":"send-keys","sessionId":"<id>","keys":["Enter"]}
{"tool":"process","action":"send-keys","sessionId":"<id>","keys":["C-c"]}
{"tool":"process","action":"paste","sessionId":"<id>","text":"line1\nline2\n"}

安全模式

exec 在 gateway 或 node 上运行时受审批控制：

• deny：完全拒绝
• allowlist：只允许审批列表中的命令（精确匹配可执行文件路径）
• full：无限制（谨慎使用）

tools.exec.safeBins 是无需审批就可使用的"安全二进制"白名单（仅支持 stdin 流式处理的小工具），不要将解释器（python、node、bash）加入此列表。

会话级覆盖（/exec）

在聊天中用 /exec 命令临时修改当前会话的执行配置：

/exec host=gateway security=allowlist ask=on-miss node=mac-1
/exec   # 显示当前配置

此设置仅影响当前 session，不写入配置文件。

apply_patch（实验性）

用于多文件结构化编辑，目前仅 OpenAI/Codex 模型支持：

{
  tools: {
    exec: {
      applyPatch: { enabled: true, workspaceOnly: true },
    },
  },
}

• workspaceOnly: true（默认）：限制在工作区目录内
• 工具策略 allow: ["exec"] 隐式允许 apply_patch

配置选项

{
  tools: {
    exec: {
      host: "sandbox",              // 默认执行位置
      pathPrepend: ["~/bin"],       // 在 PATH 前添加目录
      notifyOnExit: true,           // 后台任务结束时发通知
      safeBins: ["jq", "grep"],     // 安全二进制白名单
    },
  },
}

注意事项

• 后台会话（process）按 Agent 隔离，跨 Agent 不可见
• Windows 宿主：优先使用 PowerShell 7（pwsh），回退到 PowerShell 5.1
• 宿主执行：拒绝 env.PATH 覆盖和动态链接库劫持相关的环境变量（LD_*/DYLD_*）
• 沙箱默认关闭，未启用沙箱时显式指定 host=sandbox 会报错（不会静默回退到 gateway）