1. 为什么要在 Claude Code 外面再套一层策略Claude Code 这类终端智能体工具最大的价值在于它能直接读写文件、执行命令、跑测试、改代码。但这也正是它最让人不放心的地方——你给了它一把能开所有门的钥匙却很难在事后说清楚它到底开过哪些门、动过哪些东西。我在几个内部项目里用它做重构和批量脚本生成最开始是纯裸跑出了问题只能靠翻 shell history 和 git diff 去倒推效率极低而且经常对不上账。所谓「进程外」策略核心思路是把管控逻辑从 Claude Code 进程内部挪出来放到它外面独立的一层去拦截和记录。进程内做策略意味着你要改它的源码或者依赖它提供的钩子一旦版本升级、行为变化策略就跟着失效而且它自己记录的东西你未必信得过。进程外则相反Claude Code 还是那个 Claude Code你不动它只是在它和操作系统之间插一层壳所有它发起的敏感动作——执行命令、写文件、发起网络请求——都先经过这层壳。OpenShell 就是干这个的它提供一个受控的 shell 执行环境把命令执行、文件访问、审计日志统一收口。这套东西解决的是三个很实际的问题。第一是可审计每一次命令执行都有结构化日志谁在什么时候、以什么身份、在哪个目录、执行了什么、返回了什么全部落盘事后能复盘。第二是可拦截你可以在策略里定义哪些命令禁止执行、哪些路径禁止写入、哪些网络目标禁止访问命中就直接拒绝而不是等它跑完才发现闯了祸。第三是可复现因为所有动作都经过同一层环境变量、工作目录、超时设置都是统一的换台机器跑出来的行为一致不会因为本地 shell 配置不同而漂移。适合谁来参考如果你只是偶尔用 Claude Code 问几个问题、改改小文件那确实没必要上这套。但如果你把它接进了 CI、让它批量处理仓库、或者团队里多个人共用一套自动化流程那进程外策略基本是刚需。尤其是做量化交易策略代码生成、大数据集群部署脚本这类场景一条误执行的命令代价可能是真金白银审计日志就是你唯一的证据链。2. OpenShell 的定位与整体架构拆解2.1 OpenShell 到底是个什么东西OpenShell 不是某个特定厂商的产品名而是一类「受控 shell 执行层」的统称。它的本质是一个中间进程上游接收执行请求命令字符串、工作目录、环境变量、超时下游调用真正的系统 shell 去执行中间做策略校验和日志记录。你可以把它理解成一个带安检和监控的传送带Claude Code 把要执行的命令放上传送带传送带先检查这件「行李」合不合规合规就送过去执行执行完把结果和过程记录一并返回。它和普通的subprocess封装最大的区别在于策略是声明式的、日志是结构化的。普通封装你写一堆 if-else 判断命令里有没有rm -rf这种字符串匹配既容易漏又容易误伤。OpenShell 通常配合一套策略描述比如基于 ABAC 的属性访问控制或者简单的规则列表把「谁、在什么条件下、能对什么资源做什么操作」表达清楚判断逻辑和业务逻辑分离。2.2 为什么选进程外而不是进程内我对比过三种方案。第一种是直接用 Claude Code 自带的权限确认机制每次敏感操作弹窗让你点确认。问题是批量任务里弹窗几百次人根本点不过来最后就是无脑点允许等于没有防护。第二种是改它的配置或插件在它内部挂钩子。问题是钩子的能力和稳定性完全取决于它的实现版本一升级钩子签名变了你的策略就静默失效这种「静默失效」比没有防护更危险因为你以为还有保护。第三种就是进程外拦截Claude Code 通过一个受控的入口去执行命令这个入口是我们自己控制的它的行为不随 Claude Code 版本变化。进程外还有一个隐性好处它天然支持多工具复用。今天你用 Claude Code明天换个别的智能体工具只要它们都走这个受控入口策略和日志就是同一套不用为每个工具重新写一遍管控逻辑。这在团队里特别重要管控标准统一了审计口径才统一。2.3 整体数据流一次典型的执行请求数据流是这样的Claude Code 生成命令调用受控入口可以是一个本地 socket 服务也可以是一个包装过的可执行文件入口进程加载策略对请求做校验校验通过则 fork 出子进程执行执行过程中捕获 stdout、stderr、退出码、耗时、资源占用执行结束后把结构化日志写入日志文件或日志服务最后把结果返回给 Claude Code。整个链路里Claude Code 感知不到策略层的存在它只知道自己调用了一个 shell 并拿到了结果。这里有个设计取舍值得说同步还是异步记录日志。同步写日志保证不丢但会拖慢每次执行异步写日志快但进程崩溃时可能丢最后几条。我的做法是同步写本地文件、异步同步到远端本地文件用追加写加 fsync保证崩溃可恢复远端用批量发送兼顾性能和可靠性。3. 策略层的核心设计从规则到落地3.1 策略要管住哪几类动作不是所有动作都值得管。全管会导致策略复杂到没人维护最后被绕过。我一般把动作分成三类。高危类删除文件、修改系统配置、执行网络下载、提权操作这类必须拦截或强制审批。敏感类写代码文件、执行测试、访问数据库这类记录详细日志但不一定拦。普通类读文件、列目录、查状态这类只记摘要减少日志噪音。分类的依据是「不可逆性」和「影响范围」。删除是不可逆的所以高危写代码文件虽然重要但有 git 兜底可以回滚所以归敏感读操作无副作用归普通。这个分类不是拍脑袋是踩过坑之后总结的——早期我把所有写操作都当高危拦结果正常开发流程被卡得死死的团队直接绕过策略层裸跑防护形同虚设。3.2 策略描述用什么形式我试过三种。纯代码 if-else 最灵活但最难审计改一条规则要改代码、走 review、重新部署。配置文件YAML/JSON好审计但表达能力有限复杂条件写起来很别扭。最后我选的是规则列表加条件表达式的混合形式规则本身是配置条件用一个小型表达式引擎求值既能表达「当工作目录在 /prod 下且命令包含 deploy 时拒绝」这种复合条件又保持了配置的可读性。一个规则大概长这样匹配字段包括命令、工作目录、环境变量、调用者身份、时间窗口动作包括 allow、deny、log、require_approval优先级从高到低匹配第一条命中的规则生效。这里的关键是默认拒绝还是默认允许。生产环境我坚持默认拒绝白名单放行开发环境默认允许黑名单拦截。因为生产环境你无法穷举所有危险命令只能穷举所有允许的命令。3.3 策略的版本与灰度策略本身也是代码也要版本管理。我见过太多团队策略改了没记录出了事不知道当时生效的是哪版。做法很简单策略文件进 git每次加载时把策略内容的哈希写进每条审计日志。这样事后复盘时你能精确知道某条命令执行时生效的是哪版策略。灰度则是新策略先在小范围生效观察日志里有没有误拦确认没问题再全量。注意策略哈希一定要写进日志这是事后定责的关键。没有它你只能证明「现在」的策略是什么证明不了「当时」的策略是什么。4. 审计日志的结构化设计与分析4.1 一条合格的审计日志该有什么日志不是越详细越好而是要在需要的时候能回答关键问题。我设计的日志字段分四组。身份组调用者标识、会话 ID、父进程 ID。请求组原始命令、解析后的命令、工作目录、环境变量快照、超时设置。结果组退出码、stdout 摘要、stderr 摘要、执行耗时、峰值内存。策略组命中的规则 ID、策略版本哈希、最终动作。这里有个细节原始命令和解析后的命令要分开存。原始命令是 Claude Code 发来的字符串解析后的命令是经过 shell 解析、变量展开之后的实际执行内容。两者可能差别很大比如$HOME展开成实际路径、管道和重定向被拆解。只存原始命令事后你看不出它到底动了哪个文件只存解析后的你又对不上 Claude Code 的原始意图。两个都存才能完整还原。4.2 日志格式选 JSON Lines 还是别的我强烈推荐 JSON Lines每行一条完整 JSON。原因有三追加写天然安全不会因为并发写坏文件流式处理方便tail -f加jq就能实时看解析简单任何语言都有 JSON 库。相比之下CSV 遇到命令里带逗号、换行就崩纯文本日志要靠正则解析命令里带特殊字符就匹配错。字段命名上我习惯用扁平结构加少量嵌套避免过深嵌套导致查询麻烦。时间戳统一用 UTC 加毫秒精度别用本地时间跨时区排查时本地时间是灾难。命令内容如果太长截断存摘要完整内容另存一个文件用哈希关联避免日志文件被超长命令撑爆。4.3 从日志里能挖出什么日志的价值在于分析不是存着好看。我常用的几个分析视角频率异常某个命令在短时间内被反复执行可能是死循环或者被注入路径异常命令访问了平时不碰的目录可能是越权尝试时间异常非工作时间大量执行可能是自动化任务失控或者人为误操作失败聚集同一类命令连续失败可能是环境问题或者策略误拦。举个真实例子。有次我发现日志里find命令在某个目录下被高频执行了几百次退出码全是 0看起来正常。但结合工作目录一看它在遍历一个巨大的数据目录每次执行耗时都在涨。追下去发现是 Claude Code 生成的一个脚本里有个循环条件写错了导致无限遍历。如果没有审计日志这个任务会一直跑到磁盘 IO 打满才被发现。日志让你在问题扩大前就抓住它。5. 实操落地从零搭起这套管控5.1 环境准备与依赖先明确前提这套东西跑在 Linux 或 macOS 上最顺Windows 下因为进程模型和信号机制差异需要额外处理我建议生产环境用 Linux。依赖很轻一个 Python 3.9 或者 Go 1.20 的运行时加一个日志存储本地文件起步规模大了换 Loki 或 ClickHouse。不需要数据库也能跑但如果你要做复杂查询分析上个时序库会舒服很多。目录结构我习惯这样组织/opt/openshell/放主程序/etc/openshell/policies/放策略文件/var/log/openshell/放审计日志/var/run/openshell/放 socket 文件。权限上主程序和策略目录只读日志目录可写但只允许特定用户写socket 文件权限 600只有 Claude Code 运行的用户能连。5.2 受控入口的两种实现方式方式一包装可执行文件。写一个safe-shell脚本或二进制Claude Code 配置里把 shell 指向它。它接收参数加载策略校验执行记录。优点是简单缺点是每次执行都要启动一个新进程加载策略有开销。适合执行频率不高的场景。方式二常驻服务加客户端。起一个常驻的 OpenShell 服务监听本地 socketClaude Code 通过一个轻量客户端把请求发过去。优点是策略常驻内存响应快还能做跨请求的状态管理比如限流、会话追踪。缺点是多了一个要维护的服务。执行频率高的场景我推荐这个。我实际用的是方式二。客户端是个几十行的脚本把命令和上下文序列化发到 socket等服务返回结果再打印出来。Claude Code 那边完全无感它以为自己在跟一个普通 shell 打交道。5.3 策略加载与热更新策略不该每次执行都从磁盘读那样太慢。做法是服务启动时加载到内存同时监听策略文件的变化用 inotify 或者定时轮询文件 mtime变化了就重新加载。重新加载时要做校验语法错误、规则冲突要拒绝加载并告警保留旧策略继续生效。绝不能因为新策略有问题就导致服务不可用那样等于自己把自己锁在门外。热更新还有个细节正在执行的请求用旧策略还是新策略我的选择是请求开始时快照当前策略版本整个请求生命周期内用这个快照。这样避免一个请求执行到一半策略变了导致行为不一致也让日志里的策略哈希始终对应实际生效的版本。5.4 与 Claude Code 的对接Claude Code 执行命令的方式本质上是通过一个 shell 去跑。你要做的是让它用你的受控 shell。具体配置方式取决于它的版本和运行环境核心就是设置SHELL环境变量或者它内部的 shell 路径配置指向你的受控入口。配置完之后跑一个测试命令验证执行echo test然后去审计日志里找这条记录能找到就说明链路通了。注意对接完成后一定要做一次「故意违规」测试。手动构造一条策略里禁止的命令确认它被拦截且日志里有拒绝记录。只测正常路径不测拦截路径等于没测。6. 常见问题与排查实录6.1 命令执行卡住不返回最常见的原因是子进程的输出管道没被正确读取导致死锁。如果子进程往 stdout 写大量数据而父进程没及时读管道缓冲区满了子进程就阻塞父进程又在等子进程结束互相等死锁。解决办法是用独立的线程或协程分别读 stdout 和 stderr或者用非阻塞 IO 加 select。我早期就栽在这上面一个输出几万行的命令直接把服务卡死。排查方法看进程树找到卡住的子进程用strace看它在等什么系统调用。如果是write阻塞基本就是管道问题。6.2 策略误拦正常命令误拦通常来自字符串匹配太粗暴。比如策略里写「包含 rm 就拒绝」结果confirm、perform这种词也被拦。解决办法是解析命令结构拿到真正的命令名和参数而不是对整条字符串做子串匹配。用 shell 的词法分析器把命令拆成 token第一个 token 是命令名后面的才是参数基于 token 判断准确得多。另一个误拦来源是环境变量展开。策略里写「禁止访问 /etc」但命令里写的是$CONFIG_DIR展开后才是 /etc如果策略在展开前判断就漏了在展开后判断又可能误伤。我的做法是两阶段判断先对原始命令做粗筛再对展开后的命令做精判任一阶段命中都拦。6.3 日志丢失或写入不完整进程被 kill 时缓冲区里的日志可能没落盘。解决办法是每条日志写完立即 fsync代价是性能下降但审计场景下可靠性优先。如果性能实在扛不住退而求其次用O_APPEND加定期 fsync但要知道这有丢日志的风险。另一个原因是磁盘满了日志写不进去这个要在服务里做磁盘空间监控低于阈值就告警。6.4 高频执行导致性能瓶颈每次执行都加载策略、开日志文件、fork 进程频率一高就顶不住。优化方向策略常驻内存前面说了、日志文件保持打开复用文件描述符、用进程池或者协程池减少 fork 开销。我实测下来优化前每秒能处理几十次执行优化后能到几千次差距主要在策略加载和文件打开上。问题现象可能原因排查手段解决方向命令卡住不返回管道死锁strace 看阻塞点独立线程读输出正常命令被拦字符串匹配粗暴看命中的规则 ID改用 token 解析日志缺失未 fsync 或磁盘满查磁盘空间和日志尾部立即 fsync 加监控执行变慢策略重复加载看 CPU 和 IO 占用策略常驻内存策略不生效热更新失败看服务日志有无加载错误校验后保留旧策略6.5 几个踩过的坑第一个坑是符号链接绕过。策略禁止写/prod但攻击者或者失控的脚本通过一个指向/prod的符号链接去写如果策略只做路径字符串匹配就绕过了。解决办法是解析真实路径realpath再判断。第二个坑是环境变量污染。Claude Code 执行命令时继承的环境变量里可能藏着LD_PRELOAD之类的东西能劫持动态链接库。策略层要过滤掉这类危险环境变量只放行白名单内的。第三个坑是日志里的敏感信息。命令里可能带 token、密码直接记进日志就是泄露。做法是对命令做脱敏识别常见的敏感参数模式--password、--token替换成占位符但保留哈希以便关联。7. 日志分析的实战用法7.1 实时监控看什么实时监控不是把所有日志都刷屏那样没人看。我一般盯三个指标拒绝率短时间内拒绝率飙升说明要么有人在试探要么策略误拦两种情况都要立刻看执行时长 P99突然变长说明有慢命令拖累失败率连续失败说明环境或策略有问题。这三个指标用简单的脚本就能算超过阈值就告警。7.2 事后复盘怎么查复盘时最有用的是按会话聚合。一次 Claude Code 会话会产生一串执行记录把它们按会话 ID 串起来就能还原这次会话的完整行为轨迹它先读了什么、然后改了什么、最后跑了什么测试。这个轨迹比单条命令有用得多能看出意图和因果。我复盘过一次线上事故就是靠会话轨迹发现是某次重构时一个批量替换脚本误伤了配置文件。7.3 用日志反哺策略日志不只是事后用还能指导策略优化。定期统计被拒绝的命令看哪些是真正的威胁、哪些是误拦误拦的加白名单漏网的补规则。这个循环跑几轮策略就越来越贴合实际。我一般两周做一次这个复盘把高频误拦和新增威胁模式整理进策略。8. 一些个人体会这套东西搭起来不难难的是坚持用。我见过太多团队一开始热情很高策略配得严严实实结果被误拦几次之后嫌麻烦直接把策略改成全放行等于白搭。我的经验是策略要从宽到严渐进先只记录不拦截观察一两周日志摸清正常行为模式再针对真正的危险动作加拦截。一上来就严必然误伤误伤必然导致放弃。另一个体会是日志要有人看。存了一堆日志没人分析跟没存一样。哪怕每周花半小时扫一眼拒绝记录和异常指标价值都比存一年日志不看大。日志的价值在分析不在存储。最后分享一个小技巧给审计日志加一个每日摘要任务自动统计当天的执行总数、拒绝数、Top 命令、异常会话生成一份简短报告。这样即使不主动查也能通过报告发现异常。我现在的做法是摘要直接推到团队频道谁看到异常谁跟进比事后翻日志高效得多。这套机制跑了大半年帮我们提前拦下了好几次失控的批量脚本算是把「进程外策略」这件事真正落到了实处。