Exec 工具

在工作区中运行 shell 命令。通过 process 支持前台 + 后台执行。如果 process 不被允许，exec 同步运行并忽略 yieldMs/background。后台会话按 agent 范围；process 只能看到来自同一 agent 的会话。

参数

  • command（必需）
  • workdir（默认为 cwd）
  • env（键/值覆盖）
  • yieldMs（默认 10000）：延迟后自动后台
  • background（布尔值）：立即后台
  • timeout（秒，默认 1800）：到期时杀死
  • pty（布尔值）：在可用时在伪终端中运行（仅 TTY CLI、编码 agent、终端 UI）
  • host（sandbox | gateway | node）：在哪里执行
  • security（deny | allowlist | full）：gateway/node 的强制模式
  • ask（off | on-miss | always）：gateway/node 的批准提示
  • node（字符串）：host=node 的节点 id/名称
  • elevated（布尔值）：请求提升模式（gateway host）；仅当 elevated 解析为 full 时才强制 security=full

注意：

  • host 默认为 sandbox。
  • 当沙箱关闭时忽略 elevated（exec 已经在 host 上运行）。
  • gateway/node 批准由 ~/.openclaw/exec-approvals.json 控制。
  • node 需要配对的节点（伴侣应用或无头节点主机）。
  • 如果有多个节点可用，设置 exec.node 或 tools.exec.node 来选择一个。
  • 在非 Windows 主机上，exec 在设置时使用 SHELL；如果 SHELL 是 fish，它会优先从 PATH 使用 bash（或 sh）以避免 fish 不兼容的脚本，然后如果两者都不存在则回退到 SHELL。
  • 重要：沙箱默认关闭。如果沙箱关闭，host=sandbox 直接在 gateway host 上运行（无容器）并且不需要批准。要要求批准，使用 host=gateway 运行并配置 exec 批准（或启用沙箱）。

配置

  • tools.exec.notifyOnExit（默认：true）：当为 true 时，后台 exec 会话在退出时排队系统事件并请求心跳。
  • tools.exec.approvalRunningNoticeMs（默认：10000）：当批准门控的 exec 运行时间超过此值时发出单个"运行中"通知（0 禁用）。
  • tools.exec.host（默认：sandbox）
  • tools.exec.security（未设置时，sandbox 默认为 deny，gateway + node 默认为 allowlist）
  • tools.exec.ask（默认：on-miss）
  • tools.exec.node（默认：未设置）
  • tools.exec.pathPrepend：要在 exec 运行的 PATH 前添加的目录列表。
  • tools.exec.safeBins：可以在没有显式允许列表条目的情况下运行的仅 stdin 安全二进制文件。

示例：

{
  tools: {
    exec: {
      pathPrepend: ["~/bin", "/opt/oss/bin"]
    }
  }
}

PATH 处理

  • host=gateway：将你的登录 shell PATH 合并到 exec 环境中（除非 exec 调用已经设置 env.PATH）。守护进程本身仍然使用最小的 PATH 运行：
    • macOS：/opt/homebrew/bin、/usr/local/bin、/usr/bin、/bin
    • Linux：/usr/local/bin、/usr/bin、/bin
  • host=sandbox：在容器内运行 sh -lc（登录 shell），因此 /etc/profile 可能重置 PATH。OpenClaw 在配置文件源后通过内部环境变量（无 shell 插值）前置 env.PATH；tools.exec.pathPrepend 也适用于此处。
  • host=node：只有你传递的环境覆盖才会发送到节点。tools.exec.pathPrepend 仅在 exec 调用已经设置 env.PATH 时适用。无头节点主机仅在它前置节点主机 PATH 时才接受 PATH（无替换）。macOS 节点完全删除 PATH 覆盖。

每 agent 节点绑定（在配置中使用 agent 列表索引）：

openclaw config get agents.list
openclaw config set agents.list[0].tools.exec.node "node-id-or-name"

控制 UI：节点标签包括一个小的"Exec 节点绑定"面板用于相同的设置。

会话覆盖（/exec）

使用 /exec 为 host、security、ask 和 node 设置每会话默认值。不带参数发送 /exec 以显示当前值。

示例：

/exec host=gateway security=allowlist ask=on-miss node=mac-1

授权模型

/exec 仅对授权发送者（频道允许列表/配对加上 commands.useAccessGroups）有效。它仅更新会话状态，不写入配置。要硬禁用 exec，通过工具策略拒绝它（tools.deny: ["exec"] 或按 agent）。Host 批准仍然适用，除非你明确设置 security=full 和 ask=off。

Exec 批准（伴侣应用 / 节点主机）

沙箱化的 agent 可以在 exec 在 gateway 或节点 host 上运行之前要求每个请求的批准。有关策略、允许列表和 UI 流程，请参见 Exec approvals。

当需要批准时，exec 工具立即返回 status: "approval-pending" 和批准 id。一旦批准（或拒绝/超时），Gateway 发出系统事件（Exec finished / Exec denied）。如果命令在 tools.exec.approvalRunningNoticeMs 后仍在运行，则发出单个 Exec running 通知。

允许列表 + 安全二进制文件

允许列表强制仅匹配解析的二进制路径（无基本名称匹配）。当 security=allowlist 时，仅当每个管道段都在允许列表中或是安全二进制文件时，才自动允许 shell 命令。在允许列表模式下拒绝链接（;、&&、||）和重定向。

示例

前台：

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

后台 + 轮询：

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

发送键（tmux 风格）：

{"tool":"process","action":"send-keys","sessionId":"<id>","keys":["Enter"]}
{"tool":"process","action":"send-keys","sessionId":"<id>","keys":["C-c"]}
{"tool":"process","action":"send-keys","sessionId":"<id>","keys":["Up","Up","Enter"]}

提交（仅发送 CR）：

{"tool":"process","action":"submit","sessionId":"<id>"}

粘贴（默认使用括号）：

{"tool":"process","action":"paste","sessionId":"<id>","text":"line1\nline2\n"}

apply_patch（实验性）

apply_patch 是 exec 的子工具，用于结构化的多文件编辑。显式启用它：

{
  tools: {
    exec: {
      applyPatch: { enabled: true, allowModels: ["gpt-5.2"] }
    }
  }
}

注意：

  • 仅适用于 OpenAI/OpenAI Codex 模型。
  • 工具策略仍然适用；allow: ["exec"] 隐式允许 apply_patch。
  • 配置位于 tools.exec.applyPatch 下。
← 返回文档首页