1. 为什么要在 Claude Code 外面再套一层策略Claude Code 这类终端智能体工具最让人上头的地方就是它能直接读写文件、执行命令、跑脚本。你给它一句话它能把整个项目的重构做完。但爽归爽真把它放进生产环境或者公司内网问题马上就来了它到底执行了哪些命令有没有碰到不该碰的目录某次操作是谁触发的、什么时候触发的、结果如何这些如果全靠人肉盯屏幕基本等于没有管控。我最初用 Claude Code 的时候也是裸奔状态直到有一次它在一个测试仓库里连续跑了十几条命令其中一条差点把临时目录清空我才意识到必须给它加一层“外骨骼”。这层外骨骼的核心思路就是进程外策略——不修改 Claude Code 本身的代码也不依赖它内部的钩子机制而是在它启动之前、运行之中、退出之后用一个独立的进程去拦截、记录、审计它的行为。OpenShell 就是干这个的。你可以把它理解成一个“命令守门人”Claude Code 想执行什么先经过 OpenShell 的策略引擎符合规则的放行并记日志不符合的直接拦下并告警。整个过程对 Claude Code 是透明的它甚至不知道自己被套了一层。这样做的好处很明显——策略和工具解耦升级 Claude Code 不会影响策略调整策略也不用动 Claude Code 的配置。适合读这篇内容的人大概有三类一是已经在用 Claude Code 但心里没底的个人开发者二是需要把 AI 编码工具引入团队、但卡在合规和安全评审的工程负责人三是对进程外策略、审计日志这类基础设施感兴趣想找个真实场景练手的运维或安全同学。下面我会把整套落地过程拆开讲包括设计取舍、核心实现、实操步骤和踩过的坑。2. 整体设计思路与方案选型2.1 为什么选“进程外”而不是“进程内”给 Claude Code 加管控最直接的想法是改它的源码或者在它的配置里加钩子。但这条路有几个硬伤。第一Claude Code 是闭源分发的你拿不到源码改不了。第二就算它有配置文件支持自定义命令前缀那也只是“建议式”的Claude Code 完全可以绕过。第三进程内的钩子和 Claude Code 的版本强绑定它一升级你的钩子可能就失效了。进程外策略的逻辑完全不同。它的假设是我不信任被管控的进程我只信任操作系统给我的能力。具体来说就是利用 Linux 的ptrace、seccomp、LD_PRELOAD或者更上层的strace封装在 Claude Code 启动时把它“包”起来。所有它发起的系统调用、执行的子进程、打开的文件都会先经过我们的策略层。这个思路和容器运行时比如 runc 配合 seccomp profile是一个路数只不过我们做得更轻量、更聚焦于命令执行这一层。选进程外的另一个原因是审计的完整性。进程内钩子只能记录 Claude Code “愿意告诉你”的操作而进程外拦截能看到它“实际做了”的操作。这两者之间的差值往往就是风险所在。比如 Claude Code 内部调用了一个 shell 脚本脚本里又 fork 了子进程进程内钩子可能只看到第一层而进程外能看到整条调用链。2.2 OpenShell 在架构中的位置OpenShell 不是一个现成的开源项目它更像是一种架构模式的代称——一个轻量的 shell 包装层负责策略判定和日志落盘。在我的落地方案里它的位置是这样的用户输入 - Claude Code - OpenShell 拦截层 - 策略引擎 - 放行/拦截 - 实际执行 | v 审计日志结构化Claude Code 本身还是正常启动但它的执行环境被替换成了一个受控的 shell。这个 shell 在接收到命令后不会直接执行而是先把命令、当前工作目录、环境变量、调用者 PID 等信息打包发给策略引擎。策略引擎根据预定义的规则做判定返回 allow、deny 或 ask。allow 就直接执行deny 就返回错误码并记录ask 则挂起等待人工确认这个模式在自动化场景里一般关掉。策略引擎的规则我用的是 YAML 描述因为可读性好非技术人员也能看懂。规则的核心维度包括命令白名单/黑名单、路径访问范围、网络访问开关、执行时间窗口、调用频率限制。这些维度组合起来基本能覆盖大部分日常管控需求。2.3 审计日志的定位不只是“记录”很多人做审计日志就是简单地把命令追加到一个文本文件里。这种做法在出问题的时候基本没用因为你没法快速检索、没法关联上下文、没法做统计分析。我在设计日志格式的时候参考了结构化日志的思路每条记录是一个 JSON 对象包含以下字段字段名类型说明timestampstringISO8601 时间戳精确到毫秒session_idstring一次 Claude Code 会话的唯一标识pidint发起命令的进程 IDppidint父进程 ID用于追溯调用链commandstring原始命令全文cwdstring执行时的工作目录decisionstringallow / deny / askmatched_rulestring命中的规则 IDexit_codeint命令退出码异步回填duration_msint执行耗时stdout_hashstring标准输出的哈希用于校验完整性这个格式的好处是你可以直接用jq做查询也可以导入到 Elasticsearch 或者 ClickHouse 里做可视化。我自己的做法是日志先写本地 JSONL 文件然后用一个轻量的采集器同步到分析平台。这样即使分析平台挂了本地日志也不会丢。3. 核心细节解析与实操要点3.1 拦截层的实现方式对比实现进程外拦截有好几种技术路线我实际试过三种各有优劣。第一种是shell wrapper也就是把 Claude Code 调用的/bin/bash替换成一个自定义脚本。这个脚本接收-c参数里的命令做策略判定后再调用真正的 bash。优点是实现简单几十行代码就能跑起来缺点是只能拦截通过 shell 执行的命令如果 Claude Code 直接调用execve执行二进制就绕过去了。第二种是LD_PRELOAD 劫持通过预加载一个动态库劫持execve、fork、open等系统调用。优点是拦截粒度细能覆盖所有执行路径缺点是对静态编译的二进制无效而且和某些运行时比如 Go 编译的程序兼容性不好容易出诡异问题。第三种是ptrace 跟踪用一个父进程 attach 到 Claude Code 上实时监控它的系统调用。优点是覆盖面最全几乎无法绕过缺点是性能开销大而且实现复杂度高调试起来很痛苦。我最终选的是shell wrapper 为主、ptrace 为辅的混合方案。日常命令走 wrapper快速且低开销对于高风险操作比如直接调用二进制wrapper 会额外启动一个 ptrace 监控进程做二次确认。这样在性能和安全性之间取了个平衡。3.2 策略规则的设计原则策略规则最容易犯的错是“一刀切”。要么全放行等于没管要么全拦截Claude Code 直接没法用。我的经验是分层设计第一层命令白名单。只允许 Claude Code 执行一组预定义的基础命令比如ls、cat、grep、git、python、node、npm。其他命令一律 deny。这一层挡住了 90% 的意外操作。第二层路径约束。即使是白名单里的命令也要限制它能操作的路径。比如rm只允许在/tmp/claude-workspace/下执行git只允许在项目目录下执行。这一层挡住了“手滑删库”类的灾难。第三层网络约束。默认禁止 Claude Code 发起网络请求需要联网的操作比如npm install走单独的审批通道。这一层挡住了数据外泄和意外下载。第四层频率与时间约束。比如每分钟最多执行 60 条命令非工作时间禁止执行写操作。这一层挡住了失控的循环和异常行为。规则写的时候要注意优先级。我的做法是 deny 优先于 allow具体规则优先于通用规则。比如有一条通用规则允许python但有一条具体规则禁止python -c import os; os.system(...)那么后者生效。规则匹配用的是一个简单的决策树从上到下匹配命中即停。3.3 日志落盘的性能考量审计日志如果写得太频繁会成为性能瓶颈。我一开始用的是同步写每条命令执行完就fsync一次结果 Claude Code 跑批量任务的时候明显变慢。后来改成异步批量写入日志先写到内存队列每 100 条或者每 500 毫秒刷一次盘。这样性能上来了但引入了新的问题——如果进程崩溃队列里的日志会丢。解决办法是双写关键决策日志deny 和 ask同步写普通执行日志异步写。这样既保证了安全事件的完整性又不影响日常性能。另外日志文件按天轮转单文件超过 100MB 就切分避免单个文件过大导致检索困难。提示日志目录一定要和 Claude Code 的工作目录分开并且设置好权限。我见过有人把日志写在项目根目录下结果 Claude Code 自己把日志文件给改了审计直接失效。3.4 会话标识的传递审计日志要能关联到具体的会话否则一堆日志混在一起没法追溯。我的做法是在 Claude Code 启动时生成一个 UUID 作为session_id通过环境变量注入到它的运行环境中。OpenShell 拦截层从环境变量里读取这个 ID写进每条日志。这里有个细节Claude Code 可能会 fork 子进程子进程的环境变量会继承所以session_id能自然传递下去。但如果某个子进程主动清空了环境变量就会丢失关联。为了兜底我在日志里同时记录了pid和ppid通过进程树也能反推会话归属。4. 实操过程与核心环节实现4.1 环境准备与依赖安装我用的基础环境是 Ubuntu 22.04内核版本 5.15。Claude Code 是通过 npm 全局安装的Node 版本 20.x。OpenShell 本身用 Python 3.11 写依赖只有pyyaml和psutil都是轻量库。安装步骤很简单# 安装 Claude Code npm install -g anthropic-ai/claude-code # 创建 OpenShell 工作目录 mkdir -p /opt/openshell/{bin,conf,logs,workspace} # 安装 Python 依赖 pip install pyyaml psutil目录结构这样设计是有讲究的。bin放拦截脚本conf放策略规则logs放审计日志workspace是 Claude Code 唯一被允许写入的目录。把 workspace 单独隔离出来是为了配合路径约束规则让 Claude Code 的写操作有个明确的边界。4.2 拦截脚本的核心实现拦截脚本openshell-wrapper.sh是整个方案的门面它替代了默认的 bash。核心逻辑是接收命令调用策略引擎根据返回结果决定执行还是拒绝。#!/bin/bash # openshell-wrapper.sh REAL_BASH/bin/bash POLICY_ENGINE/opt/openshell/bin/policy_engine.py LOG_WRITER/opt/openshell/bin/log_writer.py # 提取命令 COMMAND$* CWD$(pwd) SESSION_ID${OPENSHELL_SESSION_ID:-unknown} PID$$ # 调用策略引擎 DECISION$($POLICY_ENGINE --command $COMMAND --cwd $CWD --session $SESSION_ID --pid $PID) # 解析决策结果 ACTION$(echo $DECISION | jq -r .action) RULE_ID$(echo $DECISION | jq -r .rule_id) if [ $ACTION deny ]; then $LOG_WRITER --session $SESSION_ID --pid $PID --command $COMMAND \ --cwd $CWD --decision deny --rule $RULE_ID --exit_code 126 echo OpenShell: command denied by policy $RULE_ID 2 exit 126 fi # 放行记录开始时间 START_MS$(date %s%3N) # 执行真实命令 $REAL_BASH -c $COMMAND EXIT_CODE$? # 记录执行结果 END_MS$(date %s%3N) DURATION$((END_MS - START_MS)) $LOG_WRITER --session $SESSION_ID --pid $PID --command $COMMAND \ --cwd $CWD --decision allow --rule $RULE_ID \ --exit_code $EXIT_CODE --duration $DURATION exit $EXIT_CODE这个脚本的关键点在于策略判定在命令执行之前所以 deny 的命令根本不会碰到系统。另外日志记录分两次一次在判定后记录决策一次在执行后记录结果。这样即使命令执行到一半崩溃你也能知道它被允许执行过。4.3 策略引擎的规则匹配逻辑策略引擎用 Python 实现核心是一个规则匹配函数。规则文件是 YAML 格式长这样rules: - id: allow-basic-read priority: 100 action: allow match: commands: [ls, cat, head, tail, grep, find] paths: [/opt/openshell/workspace/**, /home/user/project/**] - id: deny-rm-outside-workspace priority: 200 action: deny match: commands: [rm, rmdir] paths_not: [/opt/openshell/workspace/**] - id: deny-network-tools priority: 300 action: deny match: commands: [curl, wget, nc, ssh, scp] - id: allow-python-in-workspace priority: 150 action: allow match: commands: [python, python3, pip] paths: [/opt/openshell/workspace/**]匹配逻辑是按 priority 从高到低排序逐条匹配。匹配时先看命令是否在commands列表里再看路径是否符合paths或paths_not。全部条件满足才算命中。命中后返回该规则的 action 和 id。这里有个容易踩的坑命令匹配不能只匹配第一个词。比如python -c import os; os.system(rm -rf /)第一个词是python看起来人畜无害但实际执行的是rm。我的处理方式是对python -c、bash -c、sh -c这类“命令嵌套”的情况做二次解析把内层命令提取出来再匹配一遍。这个逻辑不复杂但能挡住很多绕过尝试。4.4 审计日志的写入与轮转日志写入器log_writer.py负责把日志追加到 JSONL 文件。核心逻辑是import json import os import time from datetime import datetime LOG_DIR /opt/openshell/logs MAX_FILE_SIZE 100 * 1024 * 1024 # 100MB def write_log(entry): entry[timestamp] datetime.utcnow().isoformat() Z date_str datetime.utcnow().strftime(%Y-%m-%d) log_file os.path.join(LOG_DIR, faudit-{date_str}.jsonl) # 检查文件大小超过阈值就轮转 if os.path.exists(log_file) and os.path.getsize(log_file) MAX_FILE_SIZE: rotated log_file f.{int(time.time())} os.rename(log_file, rotated) with open(log_file, a) as f: f.write(json.dumps(entry, ensure_asciiFalse) \n)日志轮转的策略是按天加按大小。按天是为了方便检索按大小是为了防止单日日志过大。轮转后的文件保留 30 天超期自动清理。清理脚本我放在 crontab 里每天凌晨跑一次。4.5 把 Claude Code 接入 OpenShell最后一步是让 Claude Code 使用我们的 wrapper。有两种方式第一种是修改 Claude Code 的启动配置把它的 shell 路径指向 wrapper。具体做法是在启动 Claude Code 之前设置环境变量export SHELL/opt/openshell/bin/openshell-wrapper.sh export OPENSHELL_SESSION_ID$(uuidgen) claude-code第二种是用 systemd 服务包装适合服务器场景。写一个 service 文件ExecStart指向一个启动脚本脚本里设置好环境变量再拉起 Claude Code。这样能保证每次启动都自动带上策略层不依赖人工操作。我两种都用过个人开发机上用第一种快速灵活服务器上必须用第二种因为要保证策略层不会被意外绕过。5. 常见问题与排查技巧实录5.1 命令被误拦怎么办误拦是最常见的问题。比如 Claude Code 执行git status结果被拦了因为规则里只允许了git但没允许git status这个子命令。排查的时候先看日志里的matched_rule字段找到是哪条规则拦的然后决定是放宽规则还是调整 Claude Code 的行为。我的经验是规则要按“最小可用集”来写然后根据日志逐步放宽。一开始可以只允许ls和cat跑一天看看 Claude Code 到底需要哪些命令再一条条加。这样比一开始就写一大堆规则要靠谱因为你对 Claude Code 的实际行为模式会越来越清楚。5.2 日志里出现大量重复命令如果日志里同一条命令短时间内出现几十次通常是 Claude Code 陷入了循环。这时候要检查两件事一是频率限制规则有没有生效二是 Claude Code 的任务描述是不是太模糊导致它反复尝试。频率限制我设的是每分钟 60 条超过就自动 deny 并告警。这个阈值可以根据实际任务调整批量重构的时候可以临时放宽到 200。5.3 性能明显下降如果加了 OpenShell 之后 Claude Code 明显变慢先看日志写入是不是同步的。同步写盘在机械硬盘上能拖慢十倍。改成异步批量写之后性能基本能恢复到原来的 90% 以上。另外策略引擎的规则匹配如果规则太多超过 500 条也会变慢这时候要考虑把规则分组用索引加速匹配。5.4 会话 ID 丢失如果日志里出现session_id: unknown说明环境变量没传进去。检查两点一是启动 Claude Code 之前有没有export OPENSHELL_SESSION_ID二是 wrapper 脚本里读取环境变量的逻辑有没有写错。我遇到过一次是因为 wrapper 脚本用了sudo执行环境变量被 sudo 清掉了后来在 sudoers 里加了env_keep才解决。5.5 常见问题速查表现象可能原因排查方法解决方式命令被误拦规则过严查日志 matched_rule放宽对应规则日志重复循环执行统计命令频率加频率限制性能下降同步写盘看日志写入模式改异步批量写session 丢失环境变量未传检查 env补 export 或改 sudoers日志文件过大未轮转看文件大小加轮转和清理规则不生效优先级错误看规则排序调整 priority注意策略规则改完之后一定要重启 Claude Code 会话因为规则是在启动时加载的。我踩过一次坑改完规则没重启结果新规则一直没生效排查了半天才发现是缓存问题。5.6 几个独家避坑技巧第一个技巧是给规则加版本号。每次改规则在 YAML 文件头部加一个version字段日志里也记录当前规则版本。这样出问题的时候能快速定位是哪版规则引入的。第二个技巧是定期做规则回归测试。我写了一个脚本用一组预定义的命令去跑策略引擎检查每条命令的判定结果是否符合预期。每次改规则之前先跑一遍防止改 A 规则影响了 B 规则。第三个技巧是日志里记录命令的哈希。除了记录命令全文再记录一个 SHA256 哈希。这样即使日志被篡改你也能通过哈希校验发现异常。这个做法在合规审计场景里特别有用。第四个技巧是给 deny 操作加告警。deny 日志单独走一个通道实时推送到告警平台。这样一旦有异常操作被拦截你能第一时间知道而不是等事后翻日志才发现。6. 策略层的扩展方向这套方案跑通之后能扩展的地方其实很多。比如把策略引擎从本地规则升级成远程策略服务多个 Claude Code 实例共享一套规则改一处全局生效。再比如把审计日志接入 SIEM 系统做关联分析和异常检测。还可以给策略引擎加一个“学习模式”先记录所有命令不做拦截跑一周之后自动生成一份规则建议人工审核后启用。我个人觉得最有价值的扩展是基于上下文的动态策略。现在的规则是静态的只看命令本身。如果能把当前任务类型、代码仓库的敏感级别、执行时间段这些上下文也纳入判定策略会更精准。比如同样是rm在临时目录里执行和在核心仓库里执行风险等级完全不同应该有不同的处理方式。这套东西我前后折腾了大概两周从最开始的 shell wrapper 到后来的混合拦截中间踩了不少坑。但跑顺之后心里踏实多了。Claude Code 还是那个 Claude Code能力一点没减但我知道它的每一步都在我的视线范围内。对于要把 AI 编码工具引入团队的人来说这层“外骨骼”可能是从“能用”到“敢用”之间最关键的一步。