OpenClaw exec 工具详解：命令执行与安全实践

本文聚焦：exec 工具的核心用法 + exec 的安全最佳实践

前置知识：什么是 Skill 下一篇：web_search 工具详解

在 OpenClaw 的自动化体系中，exec 工具是连接 AI 代理与操作系统底层能力的核心桥梁。它允许 Agent 执行任意 Shell 命令，从简单的文件操作到复杂的部署流程，都能通过 exec 完成。然而，强大的能力也意味着潜在的风险——不当使用可能导致安全漏洞、资源泄露甚至系统损坏。

本文将深入讲解 exec 工具的两大核心主题：核心用法（命令执行、参数配置、PTY 模式）与安全最佳实践（安全模式、超时控制、环境变量管理）。

知识点 1：exec 工具的核心用法

注意：本文中的 exec(...) 是 OpenClaw 工具调用语法，在 Skill 代码或 Agent 对话中使用，不是直接在 Shell 中执行的命令。

是什么

exec 是 OpenClaw 提供的 Shell 命令执行工具，支持同步/异步执行、PTY 模式、超时控制、环境变量注入等功能。它是构建自动化 Skill、执行部署脚本、管理远程服务器的基础工具。

为什么需要

• 自动化运维：执行系统命令、管理进程、部署应用
• Skill 开发：为自定义 Skill 提供底层执行能力
• 远程管理：通过节点（node）在远程设备上执行命令
• 交互式 CLI：PTY 模式支持需要终端交互的工具（如 vim、top、coding agents）

怎么用

基础命令执行

最简单的用法是直接执行命令并等待输出：

# 示例：查看当前工作目录
exec(command="pwd")

实际输出：

/home/guofeng/clawd

带超时控制的执行

对于可能长时间运行的命令，设置超时避免无限等待：

# 示例：执行耗时操作，10 秒超时
exec(command="sleep 5 && echo '完成'", timeout=10)

输出：

完成

如果命令超过 10 秒未完成，进程会被自动终止。

环境变量注入

向命令传递自定义环境变量：

# 示例：设置环境变量后执行
exec(
  command="echo $APP_ENV",
  env={"APP_ENV": "production", "DEBUG": "true"}
)

输出：

production

PTY 模式（伪终端）

PTY 模式用于需要 TTY 交互的 CLI 工具，如交互式 Shell、终端 UI 应用、coding agents：

# 示例：启动交互式 Bash（PTY 模式）
exec(command="bash", pty=true, yieldMs=5000)

PTY 的典型场景：

• 运行 vim、nano 等文本编辑器
• 使用 top、htop 等终端监控工具
• 启动 Coding Agent（Claude Code、Codex CLI）
• 需要颜色输出的命令（Git、ls --color）

非 PTY 的典型场景：

• 简单的文件操作（cat、cp、mv）
• 管道命令（grep、awk、sed）
• 后台服务启动（无需交互）

后台执行与进程管理

对于长时间运行的任务，使用后台模式配合 process 工具管理：

# 完整流程示例
# 1. 后台启动（返回 sessionId）
result = exec(command="npm run dev", background=true, yieldMs=1000)
# sessionId = result.sessionId

# 2. 查看日志
process(action="log", sessionId="sessionId", limit=50)

# 3. 终止进程
process(action="kill", sessionId="sessionId")

指定工作目录

# 示例：在指定目录执行命令
exec(command="git status", workdir="/home/guofeng/clawd/my-project")

常见陷阱

陷阱	说明	解决方案
忘记设置超时	长时间命令导致 Agent 卡死	始终设置 timeout 参数
PTY 滥用	简单命令用 PTY 增加开销	仅交互式 CLI 使用 pty=true
环境变量泄露	敏感变量被记录到日志	避免在 env 中传递密钥
后台进程失控	后台进程未正确管理	使用 process 工具跟踪生命周期
工作目录混淆	相对路径解析错误	显式设置 workdir 或使用绝对路径

知识点 2：exec 的安全最佳实践

安全模式（Security Mode）

exec 提供三级安全模式，控制命令执行的权限范围：

# deny - 完全禁止执行（最严格）
exec(command="ls", security="deny")
# → 拒绝执行

# allowlist - 仅允许预定义命令（推荐默认）
exec(command="ls -la", security="allowlist")

# full - 完全权限（仅受信任场景）
exec(command="rm -rf /tmp/*", security="full")

安全模式选择指南：

模式	适用场景	风险等级
deny	只读操作、沙箱环境	🔒 最低
allowlist	日常自动化、第三方 Skill	⚠️ 中等
full	受信任的管理员操作	⚠️⚠️⚠️ 高

allowlist 配置位置：在 ~/.openclaw/openclaw.json 的 tools.exec.allowlist 中定义允许的命令列表。例如：

{
  "tools": {
    "exec": {
      "allowlist": ["ls", "cat", "pwd", "git", "npm"]
    }
  }
}

超时控制（Timeout）

超时控制是防止资源耗尽和无限等待的关键防线：

# ✅ 良好实践：根据命令类型设置合理超时
exec(command="git pull", timeout=60)        # 网络操作：60 秒
exec(command="npm install", timeout=300)    # 依赖安装：5 分钟
exec(command="ls -la", timeout=10)          # 本地文件：10 秒
exec(command="docker build", timeout=600)   # 镜像构建：10 分钟

# ❌ 危险实践：不设置超时
exec(command="docker build .")  # 可能永远等待

超时设置原则：

1. 本地文件操作：5-10 秒
2. 网络请求：30-60 秒
3. 编译/构建：5-10 分钟
4. 交互式会话：根据场景动态调整

环境变量管理

环境变量是敏感信息泄露的高风险区域：

# ❌ 危险：直接传递密钥
exec(
  command="deploy.sh",
  env={"API_KEY": "sk-123…cdef"}  # 密钥可能被记录
)

# ✅ 安全：使用预配置的环境变量
exec(
  command="deploy.sh",
  env={"APP_ENV": "production"}  # 仅传递非敏感配置
)

# ✅ 更安全：通过 secrets 管理
# 在 Skill 中引用预配置的 secrets，而非硬编码

环境变量安全准则：

1. 绝不硬编码密钥：API Key、Token、密码不应出现在代码中
2. 最小化传递：只传递命令必需的变量
3. 审计日志：定期检查 exec 调用日志中的环境变量
4. 使用 secrets 管理：敏感信息通过安全的 secrets 系统注入

命令注入防护

当命令包含用户输入时，必须防止命令注入攻击：

# ❌ 危险：直接拼接用户输入
user_input = "file.txt; rm -rf /"
exec(command=f"cat {user_input}")  # 注入攻击！

# ✅ 安全：使用 shlex.quote 转义
import shlex
safe_input = shlex.quote(user_input)
exec(command=f"cat {safe_input}")

# ✅ 更安全的做法：白名单验证
allowed_files = ["file1.txt", "file2.txt"]
if user_input in allowed_files:
    exec(command=f"cat {user_input}")

命令注入防护原则：

1. 避免字符串拼接：使用参数化命令或数组形式
2. 输入验证：对用户输入进行白名单验证
3. 转义处理：必要时使用 shlex.quote() 等转义工具
4. 最小权限：以最小权限用户运行命令

远程节点执行

通过 host=node 在远程设备上执行命令时，需额外注意：

# 示例：在远程节点执行命令
exec(
  command="systemctl restart myapp",
  host="node",
  node="production-server-01",
  timeout=30
)

远程执行安全要点：

1. 节点认证：确保节点已正确配对并认证
2. 命令审计：记录所有远程执行的命令
3. 网络隔离：生产节点应与开发环境隔离
4. 回滚准备：远程命令执行前准备好回滚方案

实践建议

1. 始终设置超时：即使是简单的 ls 命令，也养成设置 timeout 的习惯。网络文件系统（NFS）或损坏的磁盘可能导致简单命令无限等待。

2. PTY 模式按需使用：PTY 模式会增加资源开销，仅在需要交互式终端时使用。对于管道命令、后台服务，保持 pty=false（默认）。

3. 安全模式分层：为不同 Skill 设置不同的安全模式。核心系统 Skill 使用 allowlist，用户自定义 Skill 根据信任度选择 deny 或 allowlist。

4. 环境变量审计：定期检查 Skill 代码中的 env 参数，确保没有硬编码的敏感信息。使用 grep -r "env=" skills/ 快速扫描。

5. 后台进程监控：使用 background=true 启动的长期进程，务必通过 process 工具定期检查状态，避免僵尸进程堆积。

相关阅读

• 创建第一个 Skill — 学习如何创建使用 exec 工具的自定义 Skill
• web_search 工具详解 — 结合搜索与命令执行，构建更强大的自动化流程
• process 工具详解 — 管理后台进程的生命周期
• 安装 Skills — 了解 Skill 的安全安装与管理

掌握 exec 工具的核心用法与安全实践，是构建可靠 OpenClaw 自动化系统的关键。记住：强大的能力需要谨慎的使用。