1. 项目概述为Claude Code构建一个本地AI“安全员”如果你正在使用Claude Code并且对让它直接在你的项目里执行rm -rf、修改系统文件或者不小心把API密钥泄露给云端模型感到一丝不安那么这个项目就是为你准备的。claude-supervisor本质上是一个为Claude Code会话设计的、AI驱动的本地安全监督与协作平台。它的核心思路很直接在Claude Code每次尝试调用一个工具比如运行Bash命令、读写文件时先按个暂停让一个本地的、离线的AI模型默认是Ollama来评估一下这个操作是否安全、合理。如果本地AI拿不准它还能把决策权交给你或者转交给更强大的Claude CLI来“二审”。我之所以花时间折腾这个是因为在真实的开发运维场景里把AI助手完全“放养”是不现实的。一次错误的sudo操作、一次对生产环境配置文件的误写代价可能很高。但频繁的人工确认又会打断工作流。claude-supervisor试图在自动化与安全性、效率与控制权之间找到一个平衡点。它不是一个简单的“开关”而是一个多层次的决策系统从完全自动化的快速审批到需要你点头的人工复核形成了一个完整的监督链条。这个项目特别适合那些需要在敏感项目如涉及客户数据、生产服务器配置、核心基础设施代码中使用Claude Code的开发者、运维工程师或技术团队。它让你既能享受AI辅助编程和运维的高效又能通过一个可审计、可干预的机制牢牢握住最终的控制权。整个系统设计为优先在本地运行这意味着你的代码、你的操作历史、你的决策数据都可以不离开你的机器这对于注重隐私和合规的团队来说是一个关键优势。2. 核心架构与设计哲学2.1 整体工作流从工具调用到最终决策理解claude-supervisor如何工作是有效使用它的前提。整个流程可以被看作一个精细化的拦截与评估管道。当你在一个已设置监督的项目中启动Claude Code并发出指令时比如“请运行测试套件”Claude Code可能会决定调用bash工具来执行npm test。此时claude-supervisor部署在项目中的钩子脚本Hook就会介入。具体来说pre-tool-use.sh这个钩子会被触发。它不会立即放行这个bash调用而是将此次调用的详细信息包括命令、参数、目标文件路径等打包成一个HTTP POST请求发送给运行在后台的claude-supervisor服务器。服务器收到请求后评估引擎开始工作。它首先会对照一套内置的静态规则进行快速匹配。例如像npm test、git status、ls -la这类公认安全的只读或常规开发命令会被自动批准响应几乎是瞬间返回Claude Code会立即执行你几乎感知不到延迟。反之像rm -rf /、dd if/dev/random of/dev/sda这类明显具有破坏性的命令会被自动拒绝。对于那些处于灰色地带的命令比如scp到某个服务器、docker run一个未知镜像、修改.env文件静态规则无法做出判断这时就轮到AI评估层上场了。这也是项目的核心。2.2 多层次AI评估策略项目采用了一个务实且高效的两层AI评估架构我称之为“本地优先云端兜底”。第一层本地Ollama模型默认且推荐这是评估的主力军。服务器会将被拦截的命令和当前会话的上下文如果涉及一起格式化成一个提示词Prompt发送给本地运行的Ollama服务。Ollama会加载你指定的模型如mistral-nemo在完全离线的环境下分析这个操作它是否符合项目安全策略是否有潜在风险操作意图是否清晰然后给出一个批准或拒绝的建议并附上一个“置信度”分数0到1之间。为什么首选本地模型速度、成本和隐私。本地推理通常在亚秒级完成没有网络延迟也无需支付API费用。最重要的是所有评估过程都在你的机器上完成操作细节不会外泄。这对于评估可能包含内部系统路径、主机名等信息的命令至关重要。第二层Claude CLI回退如果Ollama服务未运行或者本地模型评估后给出的置信度低于预设阈值例如0.8系统会自动切换到第二层。它会调用已认证的claude -p命令将同样的评估任务交给云端更强大的Claude模型如Claude 3.5 Sonnet。虽然这会产生API调用但作为“疑难杂症”的最终裁决者其判断通常更精准、更具说服力。决策与上报高置信度自动裁决如果AI无论是Ollama还是Claude的评估置信度高于阈值如0.8服务器会直接根据AI的建议自动批准或拒绝该操作并将结果返回给钩子脚本。整个过程可能在一两秒内完成。低置信度人工复核如果置信度低于阈值或者你设置了assisted辅助模式那么这个待批准的操作会被“挂起”并实时推送到Web仪表盘Dashboard的“待批准”列表中。此时你需要打开浏览器查看操作详情、AI的评估理由然后手动点击“批准”或“拒绝”。Claude Code会话会等待直到收到你的决定。2.3 关键组件交互解析整个系统的组件看似不少但协同起来逻辑清晰钩子脚本 (Hooks)它们是“哨兵”被安装到每个Claude Code项目目录的.claude/hooks/下。负责捕获事件、与服务器通信、并执行服务器返回的指令。监督服务器 (Supervisor Server)运行在localhost:3847的Node.js应用。它是“大脑”包含评估引擎、WebSocket服务、终端管理器和API路由。Web仪表盘 (Dashboard)通过浏览器访问http://localhost:3847。它是“控制台”提供实时操作审批、活动日志查看、以及基于浏览器的终端访问。Ollama服务独立的本地大模型服务提供第一层AI评估能力。Claude CLI已安装并认证的命令行工具作为评估回退和某些技能如/pensive-import的执行后端。这种架构确保了核心监督功能与Claude Code本身解耦。即使监督服务器崩溃钩子脚本也会因连接超时而“失效开放”Claude Code将恢复正常工作不会导致你的会话卡死这体现了其“优雅降级”的设计。3. 从零开始的详细部署与配置指南3.1 基础环境准备在开始之前请确保你的系统满足以下条件。我以Ubuntu/Debian系Linux为例其他系统请参考对应命令。1. 安装Node.js和npm你需要Node.js 18或更高版本。建议使用Node版本管理器如nvm进行安装方便管理多版本。# 使用nvm安装推荐 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash # 重新打开终端或运行 source ~/.bashrc nvm install 18 nvm use 18 # 或者使用系统包管理器Ubuntu/Debian # sudo apt update # sudo apt install nodejs npm # sudo npm install -g n # sudo n 182. 安装并运行OllamaOllama是运行本地模型的核心。访问 ollama.com 获取安装脚本。# 一键安装 curl -fsSL https://ollama.com/install.sh | sh # 启动Ollama服务通常会自动注册为系统服务 ollama serve # 检查服务是否运行 curl http://localhost:11434/api/tags如果看到返回模型列表或空数组[]说明服务已就绪。让这个服务在后台持续运行。3. 拉取评估模型服务器需要一个模型来进行安全评估。mistral-nemo是一个在代码和推理任务上表现均衡的中等规模模型适合作为默认选择。ollama pull mistral-nemo你也可以选择其他模型如llama3.2、qwen2.5-coder等但需要在环境变量SUPERVISOR_OLLAMA_TRUSTED_MODELS中声明服务器才会信任并使用它。4. 安装Claude Code CLI并认证确保你已从Anthropic官网下载并安装了Claude Code命令行工具并且已经通过claude auth完成了登录认证。在终端输入claude应该能打开一个交互式会话。5. 安装必要的系统工具钩子脚本和终端功能依赖一些基础工具。# jq 用于解析JSONcurl用于HTTP请求dtach用于终端会话持久化 sudo apt update sudo apt install jq curl dtach build-essential -ybuild-essential包提供了编译Node.js本地模块如node-pty所需的环境。3.2 获取并启动监督服务器1. 克隆项目仓库git clone https://github.com/sim4dim/claude-supervisor.git cd claude-supervisor2. 安装项目依赖npm install这一步会安装Express、WebSocket、node-pty等核心依赖。如果遇到关于node-pty的编译错误通常是缺少Python或make请确保build-essential已安装。3. 启动服务器最简单的启动方式node server.js默认情况下服务器会监听3847端口。你可以在浏览器中访问http://localhost:3847应该能看到登录页面如果未设置密码或直接进入仪表盘。4. 基础配置环境变量你可以通过环境变量来调整服务器行为。一种方便的方式是创建一个.env文件在项目根目录或者直接在启动命令前设置。# 示例设置密码并更改端口 SUPERVISOR_PASSWORDMySecurePass123 SUPERVISOR_PORT8080 node server.js更常见的做法是使用pm2或systemd来管理进程并注入环境变量我们稍后会讲到。3.3 将你的项目纳入监督体系这是最关键的一步将一个现有的代码项目交给claude-supervisor管理。1. 运行项目设置脚本假设你的项目路径是/home/user/my_awesome_app。# 在claude-supervisor目录下执行 ./setup-project.sh /home/user/my_awesome_app这个脚本会做以下几件事在目标项目目录中创建.claude/文件夹如果不存在。将claude-supervisor/hooks/下的所有钩子脚本复制到项目的.claude/hooks/目录。在项目的.claude/settings.json中注册这些钩子并设置CLAUDE_SUPERVISOR_URL环境变量指向监督服务器。根据模板生成或更新项目的CLAUDE.md文件注入关于监督和可用技能的说明。2. 验证钩子安装进入你的项目目录检查钩子是否就位cd /home/user/my_awesome_app ls -la .claude/hooks/你应该能看到pre-tool-use.sh,permission-request.sh等文件。3. 启动受监督的Claude Code会话现在在你的项目目录下像往常一样启动Claude Codeclaude或者你可以直接从Web仪表盘的“终端”面板点击“ New”按钮选择你的项目来启动一个会话。后者尤其方便从手机或平板电脑进行远程管理。4. 测试监督功能在Claude Code会话中尝试执行一些命令输入列出当前目录文件- 执行ls -la。这应该会被自动批准瞬间完成。输入删除根目录所有文件- Claude可能会建议rm -rf /。这应该会被自动拒绝并在Claude Code中看到拒绝信息。输入使用scp将文件复制到远程服务器- 这很可能因为涉及网络和潜在的安全风险被标记为需要人工复核。此时打开浏览器中的监督仪表盘你会在“待批准”列表中看到这个操作以及AI的评估理由由你决定是否批准。3.4 生产环境部署使用systemd对于长期运行使用systemd服务是更可靠的选择。项目提供了便捷的安装脚本。1. 安装systemd服务模板以管理员身份运行一次sudo ./install.sh这个脚本会将服务模板文件复制到/etc/systemd/system/。2. 为每个用户创建实例claude-supervisor支持多用户每个用户可以在不同的端口上运行自己的实例。假设用户alice的项目根目录在/home/alice/projects她想使用默认端口3847。sudo ./add-user.sh alice 3847 /home/alice/projects这个脚本会创建系统用户claude-supervisor-3847如果不存在来运行服务。创建配置文件/etc/claude-supervisor/3847.env用于设置该实例的环境变量如SUPERVISOR_PASSWORD,SUPERVISOR_PROJECT_ROOT。启用并启动名为claude-supervisor3847的systemd服务。3. 管理服务# 查看服务状态 sudo systemctl status claude-supervisor3847 # 查看实时日志 sudo journalctl -u claude-supervisor3847 -f # 重启服务例如在更新代码后 sudo systemctl restart claude-supervisor3847 # 停止服务 sudo systemctl stop claude-supervisor3847现在alice可以通过http://服务器IP:3847访问她专属的、受密码保护的监督仪表盘。她的所有项目只要位于/home/alice/projects下都可以用setup-project.sh进行配置并共享这个监督实例。4. 核心功能深度解析与实战技巧4.1 Web仪表盘你的全景指挥中心仪表盘不是简单的审批列表它是一个功能完整的操作中心。理解其布局和功能能极大提升效率。桌面视图900px宽度 采用左右分栏设计。左侧约占60%是终端面板右侧是审批面板。这种布局让你在监控多个Claude会话输出的同时能随时处理右侧弹出的审批请求无需切换视图。移动视图 在手机或平板上由于屏幕空间有限仪表盘会自动切换为标签页模式。你可以在“终端”和“审批”两个视图间切换。尽管屏幕小了但核心的审批、查看活动日志、筛选项目功能都完整保留。终端面板详解标签页每个活跃的Claude Code会话都会以一个标签页的形式呈现。标签页标题通常是项目名称。项目选择器点击“ New”按钮会弹出一个对话框列出SUPERVISOR_PROJECT_ROOT目录下的所有子目录。选择其一即可在该项目中启动一个新的Claude Code终端。如果该项目尚未安装钩子系统会提示你自动安装。控制权模型这是一个精妙的设计。第一个连接到某个终端标签页的浏览器窗口获得控制权可以输入命令。后续连接的同终端会话都是查看者只能看输出不能输入。查看者窗口会有一个“Take Control”按钮可以请求从当前控制者手中接管控制权。这完美解决了多人协作或从不同设备访问时的冲突问题。上下文使用率徽章每个终端标签页上会有一个小徽章显示当前会话的上下文窗口使用百分比并用颜色编码绿50%黄50-70%红70%。这是子代理Subagent强制执行功能的关键视觉提示。审批面板详解待审批队列所有被拦截且需要人工决策的操作会以卡片形式列出。每张卡片清晰展示了项目名称颜色编码、Claude想要执行的命令、AI评估的结论批准/拒绝及理由、置信度。操作按钮每个卡片有“批准”和“拒绝”按钮。即使AI已经给出了高置信度的自动裁决并已执行这里仍然会显示记录并配有“Override”按钮允许你事后否决AI的决定这对于纠正AI误判非常有用。项目筛选栏顶部有一个颜色条点击不同颜色可以快速筛选来自特定项目的审批请求在管理多个项目时极其高效。活动日志一个实时滚动的信息流记录了所有会话的工具调用、批准/拒绝事件、会话启动/停止等。这是事后审计和了解AI工作模式的宝贵资料。4.2 PII数据擦除合规性的关键盾牌个人身份信息PII泄露是AI辅助开发中的重大风险。claude-supervisor的PII擦除功能旨在从根本上防止敏感数据被发送到Anthropic的API。工作原理与路径选择 PII擦除可以在两个层面进行拦截你需要根据你的Claude Code使用模式订阅计划 vs. API密钥来选择。MCP路径适用于Claude Code Max/Pro订阅用户 如果你的Claude Code使用的是Anthropic的订阅计划代码编辑器直接与Anthropic通信你无法控制API流量。此时PII擦除通过模型上下文协议MCP实现。监督服务器会启动一个MCP服务器该服务器“劫持”了Claude Code对Read、Bash、Grep、Write、Edit等原生工具的调用。当Claude尝试读取一个文件时MCP服务器会先读取内容将其中的PII如IP、邮箱替换为令牌如[IPv4-001]再将“干净”的内容返回给Claude。当Claude要写入时MCP服务器再将令牌反向替换回真实值然后写入磁盘。这样Claude模型在整个会话中接触到的都是脱敏后的数据。API代理路径适用于API密钥部署 如果你使用自己的Anthropic API密钥并通过设置ANTHROPIC_BASE_URL环境变量将Claude Code的API请求代理到监督服务器http://localhost:3847那么PII擦除发生在API层。监督服务器会拦截发往/v1/messages的请求在将请求体转发给api.anthropic.com之前实时擦除其中的PII。Claude Code的原生工具调用不受影响只有最终发送给云端模型的对话文本被清理了。双重路径最大保障 对于安全要求极高的场景你可以同时启用MCP和API代理路径。这构成了深度防御即使某一层漏掉了某些信息另一层也可能将其捕获。配置实战 在Web仪表盘中展开“PII Scrubbing”面板。全局开关首先开启“Enable PII Scrubbing”。选择路径根据你的部署模式选择“MCP”、“API”或“Both”。选择替换模式令牌模式192.168.1.100-[IPv4-001]。优点是同一个真实值在所有会话中始终映射为同一个令牌保持了引用一致性。结构化模式192.168.1.100-10.42.17.82。它会进行按位替换保持子网结构例如.1.100和.1.101会被替换为同网段的假IP。这对于需要网络拓扑推理的任务如运维脚本至关重要因为Claude仍然能理解这些地址属于同一个子网。选择PII类型你可以精细控制擦除哪些类型的PII。默认全选但如果你确定项目中不会出现电话号码或SSN可以关闭对应选项以减少误替换。重要提示PII擦除是基于正则表达式和启发式规则进行的并非100%完美。它可能会漏掉一些非标准格式的PII或者误判一些看起来像PII的普通文本如代码中的字符串“userexample”。因此它应被视为一道重要的安全防线而非唯一的保障。对于极度敏感的数据最好的做法是永远不要将其放入AI可访问的环境。4.3 技能系统扩展Claude的协作能力技能Skills是一组预定义的、可通过斜杠命令/在受监督的Claude Code会话中调用的高级功能。它们被注入到项目的CLAUDE.md中极大地扩展了Claude的效用。核心技能实战指南/debate辩论 当你面临一个重要的技术决策如“该用微服务还是单体架构”时使用此命令。它会启动一个结构化的多智能体辩论模拟持有不同立场的专家如“ scalability_advocate”、“maintenance_specialist”进行多轮辩论最后生成一份权衡分析报告。这比直接问Claude一个开放式问题能得到更全面、更少偏见的见解。/collab协作 这个技能利用了内置的MQTT集成。假设你和同事分别在project-a和project-b中工作都运行着受监督的Claude。任何一方输入/collab可以创建一个共享的MQTT聊天室。之后双方都可以通过/ask-project技能向对方项目的Claude会话提问实现跨项目的AI协同。这对于在相关但不相同的代码库之间共享上下文非常有用。/feasibility可行性评估 基于“毛奇方法”用于对抗性计划审查。当你让Claude制定一个复杂的部署或迁移计划后使用此命令。它会创建一个“规划者”角色来阐述计划同时创建一个“ skeptical_reviewer”角色来专门挑刺、寻找潜在风险、假设漏洞和依赖问题。最终输出一份高亮风险点的审查报告。/centurion安全监控 这是一个主动安全扫描技能。运行/centurion会触发一系列检查包括扫描package.json、requirements.txt等依赖文件检查是否有已知漏洞的版本。检查项目目录中是否有意外提交的凭证文件如.env、id_rsa。检查系统进程寻找可疑活动。对比文件哈希与安全基线。 它基于security/目录下的基线文件工作你可以根据项目需要自定义这些基线。/pensive-import知识提取 这是我个人非常喜欢的功能。在一个你深耕已久的项目里运行此命令Claude会分析项目文档、SSH配置、部署脚本、README等提取出关键的操作知识例如“如何通过SSH密钥连接到生产服务器DB-01”、“本项目的测试套件需要用npm run test:integration命令启动并且需要先设置TEST_DB_URL环境变量”。这些知识会被结构化地存储到“Pensive”记忆系统中供该项目未来的所有Claude会话查询。这相当于为你的项目创建了一个不断增长的、AI可读的“运维手册”。如何添加自定义技能技能位于项目根目录的skills/文件夹下。每个技能是一个独立的目录里面至少包含一个skill.js或skill.md文件定义了该技能如何被触发和执行。研究现有技能的代码你可以很容易地创建自己的技能比如一个专门用于生成数据库迁移脚本的技能或者一个与内部工单系统集成的技能。4.4 动态审批规则让系统越用越智能初始的自动批准/拒绝规则是静态的。但claude-supervisor有一个强大的学习机制动态审批。它是如何工作的数据收集每一次AI评估无论是本地Ollama还是Claude CLI其输入命令和输出决策、置信度都会被记录到logs/eval-history.jsonl文件中。定期分析一个名为scripts/eval-housekeeping.js的维护脚本会定期运行默认每天两次。它分析历史记录寻找模式。规则生成如果一个特定的命令或命令模式出现了至少3次且历史批准率超过90%且平均AI置信度超过85%那么这个命令就会被认定为“安全模式”。规则应用生成的模式会被写入hooks/dynamic-approvals.sh文件。pre-tool-use.sh钩子脚本会“源source”这个文件。当下次再遇到完全相同的命令时钩子脚本会直接根据动态规则批准完全绕过AI评估实现亚毫秒级的响应。实战意义 这意味着随着你在特定项目中使用Claude Code系统会逐渐学习你的工作习惯。你经常运行的、被反复批准的安全命令比如项目特定的docker-compose up -d、make build会变得越来越快最终变得和ls一样瞬间通过。这既提升了效率又减少了对AI评估资源的消耗。手动触发学习 你可以随时手动运行分析脚本立即更新动态规则node scripts/eval-housekeeping.js检查生成的hooks/dynamic-approvals.sh文件你会看到类似这样的规则# 动态生成的批准规则 if [[ $tool_name bash $tool_input ~ ^npm\ run\ test:unit ]]; then echo {action:approve,reason:Dynamic approval rule matched: npm run test:unit} exit 0 fi5. 高级配置、问题排查与性能调优5.1 环境变量详解与调优环境变量是精细控制claude-supervisor行为的主要方式。以下是一些关键变量的深入解析评估后端与模型选择 (SUPERVISOR_EVAL_BACKEND,SUPERVISOR_OLLAMA_MODEL)SUPERVISOR_EVAL_BACKENDollama这是默认且推荐设置。确保你的Ollama服务稳定。SUPERVISOR_OLLAMA_MODEL如果你觉得mistral-nemo太大或太慢可以换用更小的模型如llama3.2:3b。但务必同时更新SUPERVISOR_OLLAMA_TRUSTED_MODELS变量包含你使用的模型名否则服务器会拒绝使用它导致评估失败。SUPERVISOR_MODELclaude-3-5-sonnet-20241022这是Tier 2回退时使用的Claude模型。如果你有Haiku的访问权限可以设置SUPERVISOR_FAST_MODELclaude-3-5-haiku-20241022用于一些快速决策以节省成本。置信度与超时控制 (SUPERVISOR_CONFIDENCE_THRESHOLD,SUPERVISOR_EVAL_TIMEOUT)SUPERVISOR_CONFIDENCE_THRESHOLD0.8AI评估置信度高于0.8则自动裁决。如果你希望更保守可以提高到0.9如果希望更自动化可以降低到0.7。注意过低会增加风险过高会导致几乎所有操作都需要人工复核。SUPERVISOR_EVAL_TIMEOUT60000评估超时时间毫秒。如果Ollama或Claude CLI在60秒内没有响应评估会超时。对于较慢的本地模型或网络不佳时的Claude API你可能需要适当调高此值。子代理强制执行 (SUPERVISOR_DELEGATION_ENFORCEMENT,SUPERVISOR_EVAL_ESCALATION_THRESHOLD)SUPERVISOR_DELEGATION_ENFORCEMENTtrue启用此功能后当Claude会话的上下文使用率超过SUPERVISOR_EVAL_ESCALATION_THRESHOLD默认70%时系统会强制要求Claude将复杂任务分解使用Task工具创建子代理去执行以防止主会话上下文被撑爆。这个阈值可以根据你的模型上下文窗口大小调整。对于128K上下文70%约90K tokens是合理的如果使用200K上下文的模型可以适当调高阈值。MQTT集成 (SUPERVISOR_MQTT_HOST)如果你在同一网络中有多个claude-supervisor实例或者想与其他支持MQTT的自动化工具集成可以设置此变量。实例之间可以通过MQTT广播状态、进行跨项目聊天/collab技能的基础。你可以使用Mosquitto等开源MQTT broker。5.2 常见问题与排查实录在实际部署和使用中你可能会遇到以下问题。这里记录了我的排查经验和解决方案。问题1钩子脚本执行失败Claude Code报错“Hook exited with non-zero status”症状启动Claude Code或执行命令时立即报错提示某个钩子脚本执行失败。排查步骤检查钩子脚本是否有执行权限ls -la /path/to/your/project/.claude/hooks/。确保所有.sh文件有x权限。如果没有运行chmod x /path/to/your/project/.claude/hooks/*.sh。检查监督服务器是否在运行curl http://localhost:3847/api/state。如果无响应启动服务器。检查项目中的.claude/settings.json确认CLAUDE_SUPERVISOR_URL指向正确的服务器地址和端口。手动测试钩子连接在项目目录下尝试运行CLAUDE_SUPERVISOR_URLhttp://localhost:3847 ./claude/hooks/pre-tool-use.sh {\tool_name\:\bash\, \tool_input\:\ls -la\}。观察输出和错误信息。问题2AI评估速度非常慢每次工具调用都要等好几秒症状即使是简单的ls命令也需要等待较长时间才有响应。可能原因及解决Ollama模型未加载首次使用某个模型时Ollama需要从磁盘加载会非常慢。确保Ollama服务已启动并且你指定的模型已通过ollama pull下载。可以通过ollama list查看已下载模型。Ollama服务响应慢检查Ollama服务资源占用。如果机器内存不足推理会变慢。考虑换用更小的模型如llama3.2:3b。网络问题回退到Claude CLI时如果Ollama不可用系统会回退到claude -p这需要网络请求到Anthropic API受网络延迟影响。确保网络通畅且Claude CLI已认证。动态规则未生效频繁执行的命令应该被动态规则捕获。检查logs/eval-history.jsonl是否在增长并手动运行node scripts/eval-housekeeping.js来生成规则。问题3Web终端无法启动或立即断开症状在仪表盘点击“ New”创建终端标签页一闪而过或者显示“Session exited”。排查步骤检查dtach是否安装which dtach。检查CLAUDE_BINARY环境变量指向的路径是否正确。默认是~/.local/bin/claude但你的安装路径可能不同。可以在服务器启动前设置CLAUDE_BINARY/usr/local/bin/claude。查看服务器日志journalctl -u claude-supervisor3847 -f如果使用systemd或直接看启动服务器的终端输出寻找关于spawn PTY失败的错误信息。确保运行服务器的用户有权限在SUPERVISOR_DTACH_DIR默认/tmp目录下创建socket文件。问题4PII擦除似乎没有生效真实IP仍出现在Claude的回复中症状启用了PII擦除MCP路径但Claude在分析日志时仍然提到了真实的IP地址192.168.1.100。可能原因路径选择错误如果你用的是Max/Pro计划却选择了API代理路径那是无效的因为API流量不经过你。必须选择MCP路径。MCP服务器未成功连接在Claude Code的MCP服务器设置中检查是否添加了claude-supervisor提供的MCP服务器地址通常是http://localhost:3847/mcp。在Claude Code中你可以通过快捷键通常是Cmd/Ctrl Shift P输入“MCP”来查看和管理MCP服务器连接。PII类型未匹配擦除规则基于正则表达式。某些非标准格式的IP如192.168.001.100可能无法被默认规则捕获。你可以通过仪表盘的PII Scrubbing面板临时开启“调试日志”查看具体哪些文本被匹配和替换了。问题5/skills命令在Claude会话中不显示或无法使用症状在受监督的Claude Code会话中输入/没有弹出技能列表或者提示“未知命令”。解决确保项目的CLAUDE.md文件已正确更新。setup-project.sh脚本会处理这个。你可以检查项目根目录下的CLAUDE.md文件开头部分应该包含从CLAUDE.md.template注入的技能说明。重启Claude Code会话。有时Claude Code需要重新加载CLAUDE.md才能识别新技能。检查监督服务器的skills/目录是否存在且包含技能定义。5.3 性能调优与资源管理并发评估限制 (SUPERVISOR_MAX_CONCURRENT)默认同时进行3个AI评估。如果你的机器性能强劲多核CPU足够RAM可以适当增加此值如5以支持更多并发Claude会话同时触发工具调用。但注意增加并发数也会增加Ollama或Claude API的瞬时负载。Ollama模型量化如果评估速度是瓶颈考虑为Ollama使用量化版本的模型。例如llama3.2:3b-instruct-q4_K_M在保持较好性能的同时推理速度更快内存占用更小。使用ollama pull下载量化模型并相应调整SUPERVISOR_OLLAMA_MODEL。日志管理logs/目录下的eval-history.jsonl和服务器日志会随时间增长。建议设置日志轮转logrotate或定期清理旧日志。动态审批规则生成后历史日志的主要学习价值已实现可以安全归档或删除。系统资源监控长时间运行后注意监控Node.js进程的内存使用情况。如果发现内存缓慢增长可能存在内存泄漏可以配置使用pm2等进程管理工具设置定时重启策略。6. 安全策略与最佳实践建议6.1 理解并定制安全策略项目的安全核心是supervisor-policy.md文件。它定义了AI评估时遵循的规则。你应该根据自己项目的实际情况审阅并调整这个文件。策略文件结构解析 该文件通常包含几个部分Always Approve列出无条件自动批准的操作。例如所有只读工具Read,Glob,Grep,LS以及针对项目目录内非敏感文件的Write/Edit操作。你可以在这里添加你项目特有的安全命令如npm run lint、go test ./...。Always Deny列出无条件自动拒绝的操作。这是最后的安全防线包括明显的破坏性命令rm -rf /,:(){ :|: };:、访问系统敏感目录/etc/,/boot、使用sudo提权等。强烈建议不要轻易修改这部分。Allowed With Caution需要仔细评估的操作。例如scp到已知的预配置主机、docker命令但限制在非特权模式、从可信源curl下载。AI会基于上下文如目标主机是否在白名单、Docker命令是否包含--privileged来评估。Evaluation Guidelines给AI评估模型的提示词指导它如何思考风险。例如“考虑命令是否会在项目目录之外产生副作用”、“警惕任何形式的管道到shell| bash”。如何定制备份原始的supervisor-policy.md。根据你的项目需求编辑。例如如果你在一个Kubernetes运维项目中可以将kubectl apply -f针对特定命名空间添加到“Allowed With Caution”而将kubectl delete namespace production添加到“Always Deny”。修改后需要重启claude-supervisor服务器才能使新策略生效。6.2 多用户与权限隔离实践在生产团队中部署需要考虑权限隔离。使用systemd按用户分离实例如前所述add-user.sh脚本会为每个用户创建独立的systemd服务实例、运行用户和配置文件。这意味着用户alice无法访问用户bob的仪表盘、审批队列或终端会话因为它们在完全不同的端口和进程空间下运行。强化密码认证务必为每个实例设置强壮的SUPERVISOR_PASSWORD。避免使用默认密码或弱密码。项目根目录权限确保SUPERVISOR_PROJECT_ROOT指向的目录其权限设置得当。例如/home/alice/projects应该属于alice用户其他用户不可写。防止通过项目设置脚本进行越权访问。钩子脚本安全钩子脚本本质上是Shell脚本拥有与启动Claude Code用户相同的权限。确保这些脚本本身不被恶意修改。setup-project.sh会从中央仓库复制钩子到项目目录这是一个相对安全的模式。但如果你允许用户自定义钩子则需要极高的信任度。6.3 备份与恢复策略虽然claude-supervisor本身不存储你的项目代码但它管理着重要的配置和状态。备份关键文件服务器配置/etc/claude-supervisor/目录下的所有.env配置文件。动态审批规则hooks/dynamic-approvals.sh在服务器目录以及各项目.claude/hooks/下的副本。PII映射表如果使用了PII擦除的令牌模式每个项目的PII令牌到真实值的映射表存储在服务器内存/数据库中具体位置取决于实现需要查阅文档确认是否需要备份。学习历史logs/eval-history.jsonl这是生成动态规则的原始数据。恢复流程重新部署服务器代码后将备份的.env配置文件放回原位。恢复dynamic-approvals.sh文件。对于项目重新运行setup-project.sh即可它会重新安装钩子并更新CLAUDE.md通常不需要恢复项目级的特定配置。6.4 与现有CI/CD流水线的集成思考claude-supervisor主要设计用于交互式会话但它的“延迟/恢复”机制为与自动化流程集成提供了可能。场景你有一个夜间运行的CI脚本需要使用Claude Code自动处理一些任务如代码审查、生成变更日志但其中某些操作如合并到主分支需要人工批准。潜在集成模式脚本中嵌入钩子调用在你的CI脚本中设置与监督服务器相同的环境变量并确保钩子脚本在路径中。当Claude Code在无头headless模式下运行时遇到需要审批的操作它会通过钩子向服务器发送请求并等待。利用Webhook或API监督服务器的仪表盘是一个Web应用。理论上你可以编写一个脚本定期轮询服务器的/api/state接口或特定的审批API获取待审批列表然后根据自定义逻辑或通知人工进行处理。不过当前版本并未完全暴露所有状态的RESTful API这需要一定的定制开发。“监督即代码”最理想的方式是将审批策略尽可能多地编码到supervisor-policy.md和动态规则中使得在CI环境中的绝大多数操作都能自动通过仅将极少数高风险操作设置为需要人工复核并通过仪表盘进行集中管理。最后的心得claude-supervisor最大的价值在于它提供了一种“可调节的自动化”。你并非在“完全信任AI”和“完全不信任AI”之间二选一而是可以通过策略文件、置信度阈值、动态学习层精细地控制AI在何处、以何种程度自主行动。初期建议设置较严格的策略和较高的置信度阈值多进行人工复核。随着动态规则的学习和你对系统信心的增加再逐步放宽限制让AI承担更多常规工作而你则专注于处理那些真正复杂、高风险的决策点。这种渐进式的信任建立过程才是人机协作的安全之道。