人工智能大模型LLM 网关AI Agent即时通讯【免费下载链接】openclaw-zero-tokenOpenClaw: Use All Major AI Models NO API Token! Claude/ChatGPT/Gemini/DeepSeek/Doubao/Grok/Qwen/Manus/Kimi项目地址https://gitcode.com/gh_mirrors/op/openclaw-zero-token点击查看免费下载本文基于 OpenClaw 官方文档 exec.md 与仓库源码系统讲解 exec 工具的完整用法前台/后台执行模型与yieldMs/background语义、host/security/ask三级执行路由、PATH 与环境变量安全策略、/exec会话级覆盖、exec 审批流程、allowlist 与 safe bins 机制以及实验性apply_patch子工具。读完后你将能够在 OpenClaw 中安全地驱动任意 shell 命令、管理后台进程会话并配置符合最小信任原则的执行策略。exec 是什么前台 后台双模执行exec 是 OpenClaw Agent 在 workspace 中运行 shell 命令的核心工具支持前台同步执行也支持通过process工具接管后台执行如果process工具被禁用工具策略 denyexec 会退化为同步执行并忽略yieldMs/background参数此时会附带警告 Warning: background execution is disabled; running synchronously.后台会话background sessions按 agent 隔离作用域process只能看到同一个 agent 发起的会话跨 agent 不可见。从源码看会话隔离由 process 工具 中的scopeKey过滤实现isInScope对每个会话的scopeKey做匹配exec 创建时通过defaults?.scopeKey注入该键。参数一览exec 的参数定义在 execSchema 中与文档逐项对应参数类型说明commandstring必填要执行的 shell 命令workdirstring工作目录默认取 cwdenvobject环境变量 key/value 覆盖yieldMsnumber默认 10000等待该时长后自动转后台backgroundbool立即转后台timeoutnumber秒默认 1800超时杀死进程ptybool在可用时以伪终端PTY运行适用于 TTY-only CLI、coding agent、终端 UIhoststring执行位置sandbox \| gateway \| nodesecuritystringgateway/node的强制模式deny \| allowlist \| fullaskstringgateway/node的审批提示off \| on-miss \| alwaysnodestringhostnode时指定的 node id/名称elevatedbool请求 elevated 模式gateway host仅当 elevated 解析为full时才强制securityfull几个关键的默认值在源码中有精确约束yieldMs会被钳制到10120000 毫秒之间可通过环境变量PI_BASH_YIELD_MS修改默认值见 createExecToolbackgroundtrue等价于把 yield 窗口设为 0立即 resolve 为后台yieldWindow 计算逻辑timeout默认1800 秒30 分钟到点强制终止命令输出上限前台聚合输出默认 200,000 字符DEFAULT_MAX_OUTPUT可用PI_BASH_MAX_OUTPUT_CHARS调整后台 pending 输出默认 30,000 字符DEFAULT_PENDING_MAX_OUTPUT见 常量定义。exec 的官方描述也写明了使用意图Execute shell commands with background continuation. Use yieldMs/background to continue later via process tool. Use ptytrue for TTY-required commands (terminal UIs, coding agents).工具描述。文档列出的 10 条行为约定Notes原文档的 Notes 全部值得逐条留意这里完整继承并补充源码佐证host默认sandboxelevated在 sandbox 关闭时被忽略——因为 exec 本来就在宿主上运行无需再提升gateway/node的审批由~/.openclaw/exec-approvals.json控制——源码中tools.exec.ask未显式设置时会回落到该文件的defaults.askask 解析node需要已配对的 nodecompanion app 或 headless node host多个 node 可用时通过exec.node参数或tools.exec.node配置选择其一非 Windows 宿主上使用$SHELL若SHELL是fish则优先从PATH找bash或sh以避免 fish 不兼容脚本两者都不存在才回退到SHELL。这一逻辑与 getShellConfig 完全一致Windows 宿主优先探测 PowerShell 7pwsh依次检查 Program Files、ProgramW6432再到 PATH最后回退到 Windows PowerShell 5.1resolvePowerShellPath。之所以不用 cmd.exe是因为许多 Windows 系统工具通过 WriteConsole API 直接写控制台、绕过 stdout 管道而 PowerShell 能正确捕获重定向输出见 Windows 分支注释宿主执行gateway/node拒绝env.PATH和 loader 覆盖LD_*/DYLD_*防止二进制劫持或注入代码OpenClaw 会在派生命令环境中设置OPENCLAW_SHELLexec包括 PTY 与 sandbox 执行便于 shell/profile 规则识别 exec 工具上下文。该值在 bash-tools.exec-runtime.ts 注入并有专门测试覆盖gateway 场景测试 和 PTY 场景测试重要sandbox 默认关闭off by default。若 sandbox 关闭且显式配置/请求了hostsandboxexec 会fail closed直接报错失败而不是悄悄落到 gateway 宿主上执行。此时应当启用 sandboxing或改用带审批的hostgateway。对应实现见 sandbox 可用性检查错误信息会明确提示启用agents.defaults.sandbox.modenon-main或all。此外还有一条容易遗漏脚本预检preflight只检查有效workdir边界内的文件。若脚本路径解析到workdir之外则该文件跳过预检。host 路由sandbox / gateway / node 的决策与限制exec 的host参数决定命令在哪里执行。源码中的决策链createExecTool比文档描述更严格请求的host必须与配置值tools.exec.host完全一致否则直接抛错exec host not allowed (requested ...; configure tools.exec.host... to allow).唯一例外是elevatedtrue此时host被强制改写为gatewaysecurity取配置值与请求值的交集方向最严格值minSecurityask取更严格值maxAsk——即单次调用只能收紧、不能放松审批elevated 解析为full模式时security直接置为full且ask置为off绕过审批。security的默认值随 host 变化sandbox 默认denygateway/node 未设置时默认allowlistsecurity 解析。PATH 处理与环境变量安全PATH 是 exec 安全模型中最重要的变量。原文档的 PATH handling 小节按 host 分为三种情况完整继承如下hostgateway会把登录 shell 的PATH合并进 exec 环境env.PATH覆盖在宿主执行中被拒绝。daemon 自身仍运行在极简PATH下macOS/opt/homebrew/bin、/usr/local/bin、/usr/bin、/binLinux/usr/local/bin、/usr/bin、/bin源码中对应 login-shell PATH 获取与合并getShellPathFromLoginShellapplyShellPath。hostsandbox容器内以sh -lclogin shell运行因此/etc/profile可能重置PATH。OpenClaw 在 profile source 之后通过内部环境变量前置env.PATH无 shell 插值避免注入tools.exec.pathPrepend在此同样生效hostnode只把未被屏蔽的 env 覆盖发送到 node。env.PATH覆盖在宿主执行中被拒绝、在 node host 上被忽略。若 node 需要额外 PATH 条目应配置 node host 服务的运行环境systemd/launchd或把工具安装到标准位置。宿主执行的环境变量净化集中在 sanitizeHostExecEnvWithDiagnosticsblockPathOverrides: true时任何env.PATH覆盖都会抛出Security Violation: Custom PATH variable is forbidden during host execution.单个其他危险键LD_*/DYLD_*等被拦截时抛Security Violation: Environment variable key is forbidden during host execution.多个键被拦截时聚合报错并列出 blocked/invalid 清单。通用的净化规则与 fail-closed 校验见 sanitizeHostBaseEnv / validateHostEnv。tools.exec.pathPrepend只对本地gateway与 sandbox 有意义当hostnode时该配置被忽略并附加警告 tools.exec.pathPrepend is ignored for hostnode. Configure PATH on the node host/service instead.pathPrepend 分支。每 agent 绑定 node配置方式使用 agent 列表下标配置中的索引openclaw config get agents.list openclaw config set agents.list[0].tools.exec.node node-id-or-nameControl UI 中Nodes 标签页提供了一个小的 Exec node binding 面板可配置同样的设置。配置项全解tools.exec.*原文档 Config 小节的全部配置项如下默认值已与源码核对配置键默认值说明tools.exec.notifyOnExittrue为 true 时后台 exec 会话退出后入队一个 system event 并请求 heartbeat源码defaults?.notifyOnExit ! false见 notifyOnExit 解析tools.exec.approvalRunningNoticeMs10000审批门控的 exec 运行超过该毫秒数时发出一次running 通知0表示禁用resolveApprovalRunningNoticeMs默认常量 10_000tools.exec.hostsandbox默认执行位置tools.exec.securitysandbox 为denygateway node 未设置时为allowlist执行安全模式tools.exec.askon-miss审批提示模式tools.exec.node未设置默认目标 nodetools.exec.pathPrepend—exec 运行时前置到PATH的目录列表仅 gateway sandboxtools.exec.safeBins—仅 stdin 的安全二进制可运行于无显式 allowlist 条目行为细节见 Safe binsstdin-onlytools.exec.safeBinTrustedDirs—safeBins路径检查额外信任的显式目录。PATH条目永不被自动信任内建默认为/bin和/usr/bintools.exec.safeBinProfiles—每个 safe bin 的可选自定义 argv 策略minPositional、maxPositional、allowedValueFlags、deniedFlagspathPrepend的文档示例{ tools: { exec: { pathPrepend: [~/bin, /opt/oss/bin], }, }, }退出通知的实际行为maybeNotifyOnExit仅对已后台化且未通知过的会话生效汇总文本形如Exec completed (abcd1234, code 0) :: 输出尾部 400 字符然后入队 system event 并请求一次 scoped heartbeatreason 为exec:session-id:exit。默认成功但输出为空时不通知除非显式开启notifyOnExitEmptySuccess。会话级覆盖/exec指令用/exec可为当前会话设置host、security、ask、node的会话级默认值不带参数发送/exec可查看当前值。/exec hostgateway securityallowlist askon-miss nodemac-1该指令的解析实现在 parseExecDirectiveArgs按keyvalue或key:valuetoken 切分host只接受sandbox|gateway|node、security只接受deny|allowlist|full、ask只接受off|on-miss|always非法取值会被标记为 invalid 而不生效。授权模型/exec只对授权发送者生效渠道 allowlist/pairing 加上commands.useAccessGroups。它只更新会话状态不写配置。要硬性禁用 exec应通过工具策略拒绝tools.deny: [exec]或按 agent 配置。除非你显式设置securityfull且askoff否则宿主审批依然适用。Exec 审批companion app / node host沙箱化的 agent 可以在exec落到 gateway 或 node 宿主执行前要求逐次审批。策略、allowlist 与 UI 流程的完整细节见 Exec approvals。审批流程的关键行为均有源码对应需要审批时exec 工具立即返回status: approval-pending和一个 approval id提示消息由 buildApprovalPendingMessage 生成包含短代码8 位 slug、完整 id、host/node、CWD、命令代码块并给出回复格式Reply with: /approve slug allow-once|allow-always|deny背景模式要求预授权策略allow-always 或askoff审批超时默认 120 秒DEFAULT_APPROVAL_TIMEOUT_MS 120_000请求超时 130 秒见 常量审批通过或拒绝/超时后Gateway 发出 system eventExec finished/Exec denied若命令批准后仍在运行且超过tools.exec.approvalRunningNoticeMs只发出一次Exec running通知。Allowlist 与 safe bins手动 allowlist 只匹配解析后的二进制路径resolved binary paths不做 basename 匹配。securityallowlist时shell 命令只有在每个管道段都在 allowlist 中或属于 safe bin 时才被自动放行链式命令;、、||在 allowlist 模式下被拒绝除非每个顶层段都满足 allowlist含 safe bin重定向redirection始终不支持autoAllowSkills是 exec approvals 中一条独立的便捷路径不等于手动 allowlist 条目。若追求严格显式信任保持autoAllowSkills关闭四个控制项各司其职tools.exec.safeBins小的、仅 stdin 的流过滤器tools.exec.safeBinTrustedDirssafe-bin 可执行路径的显式额外信任目录tools.exec.safeBinProfiles自定义 safe bin 的显式 argv 策略allowlist对可执行路径的显式信任。不要把safeBins当作通用 allowlist也不要加入解释器/运行时二进制如python3、node、ruby、bash——需要这些时请使用显式 allowlist 条目并保持审批提示开启。源码中对此有启动期检查未配置 profile 的 safeBins 条目会被忽略并打日志解释器类条目会被单独警告 interpreter/runtime binaries in safeBins (...) are unsafe without explicit hardened profilessafe bin 策略解析策略实现见 resolveExecSafeBinRuntimePolicy。此外openclaw security audit会在解释器/运行时safeBins条目缺少显式 profile 时给出警告openclaw doctor --fix可以为缺失的自定义safeBinProfiles条目生成脚手架。完整策略与示例见 Safe bins versus allowlist。实战示例前台执行{ tool: exec, command: ls -la }后台 轮询{tool:exec,command:npm run build,yieldMs:1000} {tool:process,action:poll,sessionId:id}命令在yieldMs到期后自动转后台exec 返回的提示文本形如Command still running (session id, pid pid). Use process (list/poll/log/write/kill/clear/remove) for follow-up.resolveRunning。poll的timeout参数表示最多等待的毫秒数上限 120,000 msMAX_POLL_WAIT_MS。process 工具支持的完整动作集为list、poll、log、write、send-keys、submit、paste、kill、clear、removeprocessSchemalog默认返回最后 200 行可用offset/limit分页。发送按键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]}按键编码在 pty-keys.ts 中实现测试见 bash-tools.process.send-keys.test.ts。提交只发 CR{ tool: process, action: submit, sessionId: id }粘贴默认 bracketed 模式{ tool: process, action: paste, sessionId: id, text: line1\nline2\n }paste支持bracketed布尔参数控制是否用 bracketed paste 模式包裹。apply_patch实验性apply_patch是exec的子工具subtool用于结构化多文件编辑需要显式启用{ tools: { exec: { applyPatch: { enabled: true, workspaceOnly: true, allowModels: [gpt-5.2] }, }, }, }注意事项与文档逐条对应仅对 OpenAI / OpenAI Codex 模型可用工具策略仍然生效allow: [exec]会隐式允许apply_patch配置位于tools.exec.applyPatchtools.exec.applyPatch.workspaceOnly默认true限制在工作区内只有在你有意希望apply_patch在工作区目录之外写/删文件时才设为false。从源码看patch 采用*** Begin Patch/*** End Patch标记格式支持*** Add File:、*** Delete File:、*** Update File:、*** Move to:、变更上下文与*** End of File标记标记定义与 hunk 结构。workspaceOnly在 createApplyPatchTool 中默认为trueoptions.workspaceOnly ! false每次应用都会逐 hunk 检查AbortSignal并返回added/modified/deleted三类操作汇总。测试覆盖见 apply-patch.test.ts。失败语义与超时提示补充一个文档未展开但对调试重要的细节exec 会把退出结果分类为completed/failed失败原因failureKind包括shell-command-not-foundexit 127、shell-not-executableexit 126、overall-timeout、no-output-timeout、signal、abortedclassifyExecFailureKind 与 formatExecFailureReason。超时提示会明确建议提高超时例如 Command timed out after 30 seconds. ... re-run with a higher timeout (e.g., exec timeout300).。值得注意的是后台化请求background/yieldMs且未显式指定timeout会豁免整体超时backgroundTimeoutBypass因为长任务本应通过process轮询管理。小结OpenClaw 的 exec 工具围绕默认保守、显式放宽构建host必须与配置一致、sandbox 未启用时 fail closed、宿主执行拒绝PATH/loader 环境变量覆盖、allowlist 只认解析后的完整路径、safe bins 限制为 stdin-only 过滤器且审批只能收紧不能放松minSecurity/maxAsk。在这套约束之上yieldMs/backgroundprocess提供了完整的前后台进程生命周期管理poll、log、write、send-keys、submit、paste、kill/exec提供了不污染全局配置的会话级临时覆盖。相关源码入口集中在 src/agents/bash-tools.exec.ts、src/agents/bash-tools.exec-runtime.ts、src/agents/bash-tools.process.ts、src/agents/shell-utils.ts、src/agents/apply-patch.ts审批策略详解可继续查阅 docs/tools/exec-approvals.md。赞分享人工智能大模型LLM 网关AI Agent即时通讯【免费下载链接】openclaw-zero-tokenOpenClaw: Use All Major AI Models NO API Token! Claude/ChatGPT/Gemini/DeepSeek/Doubao/Grok/Qwen/Manus/Kimi项目地址https://gitcode.com/gh_mirrors/op/openclaw-zero-token点击查看免费下载相关推荐OpenClaw exec 工具全解析从命令执行、后台会话到审批授权与安全边界OpenClaw exec 工具全解析从命令执行、后台会话到审批授权与安全边界 exec 是 OpenClaw 中驱动 Agent 操作真实系统的核心工具它人工智能AI Agent即时通讯后端本地部署语音OpenClaw Exec Host 重构方案sandbox / gateway / node 三级执行路由与审批体系详解OpenClaw Exec Host 重构方案sandbox / gateway / node 三级执行路由与审批体系详解 导读 本文基于 OpenClaw人工智能AI Agent即时通讯后端本地部署语音OpenClaw 主机命令执行审批Exec Approvals完整指南allowlist、safe bins 与跨渠道审批实战OpenClaw 主机命令执行审批Exec Approvals完整指南allowlist、safe bins 与跨渠道审批实战 导读 Exec Appro人工智能大模型LLM 网关AI Agent即时通讯上一篇国家中小学智慧教育平台电子课本下载神器三步轻松获取PDF教材的完整指南下一篇解决Obtainium中腾讯应用商店APK下载链接解析问题从报错到修复的完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考