0%

Claude Code 源码解析 (1)：Bash 命令执行的安全艺术

架构师点评：Bash 安全不是“禁止执行命令”，而是让 AI 在可授权、可回滚、可审计的边界内执行命令。企业引入 Claude Code 或自研 Coding Agent 时，命令权限模型必须早于自动化能力上线。

导读： 这是 Claude Code 20 个功能特性源码解析系列的第 1 篇，深入分析 Bash 命令执行的安全设计艺术。

问题引入：AI 执行命令的风险

痛点场景

想象这样一个场景：

1
2
3
4
5
6
7
用户："帮我清理一下 node_modules"

AI 执行：rm -rf node_modules  ✅ 正确

但如果 AI 理解错了...

AI 执行：rm -rf /  ❌ 灾难！

这不是危言耸听。 AI 助手拥有强大的执行能力，但必须确保安全可控。

核心问题

设计 AI 助手的 Bash 工具时，面临以下挑战：

  1. 能力与安全的平衡

    • AI 需要执行命令来完成工作
    • 但危险命令可能导致系统损坏

  2. 理解与误判的风险

    • AI 可能误解用户意图
    • 路径解析错误可能导致误删

  3. 权限控制的粒度

    • 所有命令同等对待？
    • 还是分级处理？

  4. 用户体验的考量

    • 每次执行都确认？太繁琐
    • 完全不确认？太危险

Claude Code 给出了完整的答案。

设计思想：为什么这样设计

思想 1：多层防御，不依赖单一检查

问题： 如果只有一层检查，漏掉了怎么办？

解决： 多层防御，每层都有不同的检测维度。

1
2
3
模式匹配 → 语义分析 → 路径验证 → 权限决策
   ↓           ↓           ↓          ↓
 已知模式    意图理解    范围限制    智能判断

每层的价值：

层级 优势 局限
模式匹配 快速、准确 只能识别已知模式
语义分析 理解意图 需要额外依赖
路径验证 防止越权 无法判断命令本身
权限决策 智能灵活 可能误判

多层组合 = 95%+ 的危险命令拦截率

思想 2：权限分级，不同风险不同对待

问题： 所有命令都确认，效率太低；都不确认，风险太高。

解决： 根据风险级别分级处理。

风险级别 命令示例 处理方式
critical rm -rf / 直接拒绝
high chmod 777 强制确认 + 备份
medium git push 简化确认
low ls -la 事后通知

设计智慧：

不是一刀切，而是精细化治理。

思想 3：AI 辅助，人类决策

问题： 规则无法覆盖所有场景，AI 判断可能出错。

解决： 规则优先，AI 辅助，人类最终决策。

1
2
3
4
5
明确规则 → 自动决策 (快速)
    ↓
模糊情况 → AI 判断 (智能)
    ↓
低置信度 → 人类确认 (安全)

AI 分类器 Prompt：

1
2
3
4
5
6
7
8
9
10
11
12
分析以下命令的安全性：

命令：{command}
执行者：{agent}
当前目录：{cwd}

请判断：
1. 是否有破坏性风险？
2. 是否需要用户确认？
3. 置信度 (0-1)

返回 JSON: {"safe": boolean, "reason": string, "confidence": number}

思想 4：审计日志，可追溯

设计： 所有命令执行都记录日志。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
async function logCommandExecution(
  command: string,
  result: CommandResult,
  context: ToolContext
) {
  await gateway.log({
    type: 'bash_command',
    command,
    agent: context.agent,
    user: context.user,
    timestamp: new Date().toISOString(),
    result: result.exitCode,
    duration: result.duration,
  });
}

日志用途：

  • 安全审计
  • 问题排查
  • 行为分析
  • 优化规则

OpenClaw 最佳实践

实践 1：创建 Bash 工具插件

目录结构：

1
2
3
4
5
6
~/.openclaw/extensions/bash-tool/
├── index.ts
├── tools/
│   └── BashTool.ts
├── config.yaml
└── package.json

插件入口：

1
2
3
4
5
6
7
8
9
10
11
12
13
// index.ts
import { BashTool } from './tools/BashTool';

export const plugin = {
  name: 'bash-tool',
  version: '1.0.0',
  
  async init(gateway: any) {
    const config = loadConfig();
    gateway.registerTool('bash', new BashTool(config));
    console.log('[bash-tool] Registered');
  },
};

实践 2：配置权限规则

步骤：

1
2
3
4
5
6
7
8
9
10
11
# 1. 创建配置文件
mkdir -p ~/.openclaw/config
vim ~/.openclaw/config/bash-permissions.yaml

# 2. 编辑规则 (参考上面的配置示例)

# 3. 重启 Gateway
openclaw gateway restart

# 4. 验证
openclaw gateway status | grep bash-tool

实践 3：与审批系统集成

代码示例：

1
2
3
4
5
6
7
8
9
10
11
// 请求审批
const approval = await context.requestApproval({
  type: 'bash_command',
  command: input.command,
  risk: securityResult.severity,
  reason: securityResult.reason,
});

if (!approval.approved) {
  return { success: false, error: '用户拒绝' };
}

审批流程：

1
2
3
4
5
6
7
8
9
AI 请求审批
   ↓
Gateway 通过微信/飞书发送通知
   ↓
用户回复"同意"或"拒绝"
   ↓
Gateway 返回审批结果
   ↓
AI 继续执行或取消

实践 4：审计日志查询

查询命令执行历史：

1
2
3
4
5
6
7
8
# 查看最近执行的命令
openclaw logs bash --limit 50

# 查看特定用户的命令
openclaw logs bash --user john

# 查看失败的命令
openclaw logs bash --status failed

日志格式：

1
2
3
4
5
6
7
8
9
10
11
{
  "type": "bash_command",
  "command": "npm install",
  "agent": "devops",
  "user": "john",
  "timestamp": "2026-04-03T19:30:00Z",
  "result": 0,
  "duration": 1523,
  "decision": "allow",
  "decisionSource": "rule"
}

系列文章：

  • [1] Bash 命令执行的安全艺术 (本文)
  • [2] 差异编辑：AI 与人类的沟通语言 (待发布)
  • [3] 文件模式匹配的底层原理 (待发布)
  • …

参考资料：

  • Claude Code 源码分析：~/claude-code-analysis/features/01-bash-execution/
  • OpenClaw 文档：https://docs.openclaw.ai

企业落地建议

这篇源码解析对应的是企业 AI Coding 平台里的基础治理能力，建议落地时重点关注：

  1. 把命令分为只读、可修改、高风险、禁止四类：并明确审批策略。
  2. 对 rm、curl|sh、凭据读取、网络扫描等命令做静态规则和运行时拦截。：对 rm、curl|sh、凭据读取、网络扫描等命令做静态规则和运行时拦截。
  3. 保留完整命令审计日志：至少记录发起人、上下文、工作目录、退出码和输出摘要。
  4. 把 Bash 权限策略纳入团队 AI Coding 规范：而不是依赖个人自觉。

相关入口：

Claude Code 系列的价值，不只是学习一个工具，而是拆解企业级 Coding Agent 应该具备的工程能力：上下文、权限、任务、工具、安全和可观测。