当前位置：首页 > news >正文

为Claude Code构建本地AI安全监督平台：实现自动化与安全性的平衡

news 2026/5/3 5:43:28

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 18

2. 安装并运行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 用于解析JSON，curl用于HTTP请求，dtach用于终端会话持久化 sudo apt update sudo apt install jq curl dtach build-essential -y

build-essential包提供了编译Node.js本地模块（如node-pty）所需的环境。

3.2 获取并启动监督服务器

1. 克隆项目仓库

git clone https://github.com/sim4dim/claude-supervisor.git cd claude-supervisor

2. 安装项目依赖

npm install

这一步会安装Express、WebSocket、node-pty等核心依赖。如果遇到关于node-pty的编译错误，通常是缺少Python或make，请确保build-essential已安装。

3. 启动服务器最简单的启动方式：

node server.js

默认情况下，服务器会监听3847端口。你可以在浏览器中访问http://localhost:3847，应该能看到登录页面（如果未设置密码）或直接进入仪表盘。

4. 基础配置（环境变量）你可以通过环境变量来调整服务器行为。一种方便的方式是创建一个.env文件在项目根目录，或者直接在启动命令前设置。

# 示例：设置密码并更改端口 SUPERVISOR_PASSWORD=MySecurePass123 SUPERVISOR_PORT=8080 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 Code：

claude

或者，你可以直接从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-supervisor@3847的systemd服务。

3. 管理服务

# 查看服务状态 sudo systemctl status claude-supervisor@3847 # 查看实时日志 sudo journalctl -u claude-supervisor@3847 -f # 重启服务（例如，在更新代码后） sudo systemctl restart claude-supervisor@3847 # 停止服务 sudo systemctl stop claude-supervisor@3847

现在，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的普通文本（如代码中的字符串“user@example”）。因此，它应被视为一道重要的安全防线，而非唯一的保障。对于极度敏感的数据，最好的做法是永远不要将其放入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 fi

5. 高级配置、问题排查与性能调优

5.1 环境变量详解与调优

环境变量是精细控制claude-supervisor行为的主要方式。以下是一些关键变量的深入解析：

评估后端与模型选择 (SUPERVISOR_EVAL_BACKEND,SUPERVISOR_OLLAMA_MODEL)

SUPERVISOR_EVAL_BACKEND=ollama：这是默认且推荐设置。确保你的Ollama服务稳定。
SUPERVISOR_OLLAMA_MODEL：如果你觉得mistral-nemo太大或太慢，可以换用更小的模型，如llama3.2:3b。但务必同时更新SUPERVISOR_OLLAMA_TRUSTED_MODELS变量，包含你使用的模型名，否则服务器会拒绝使用它，导致评估失败。
SUPERVISOR_MODEL=claude-3-5-sonnet-20241022：这是Tier 2回退时使用的Claude模型。如果你有Haiku的访问权限，可以设置SUPERVISOR_FAST_MODEL=claude-3-5-haiku-20241022用于一些快速决策，以节省成本。

置信度与超时控制 (SUPERVISOR_CONFIDENCE_THRESHOLD,SUPERVISOR_EVAL_TIMEOUT)

SUPERVISOR_CONFIDENCE_THRESHOLD=0.8：AI评估置信度高于0.8则自动裁决。如果你希望更保守，可以提高到0.9；如果希望更自动化，可以降低到0.7。注意，过低会增加风险，过高会导致几乎所有操作都需要人工复核。
SUPERVISOR_EVAL_TIMEOUT=60000：评估超时时间（毫秒）。如果Ollama或Claude CLI在60秒内没有响应，评估会超时。对于较慢的本地模型或网络不佳时的Claude API，你可能需要适当调高此值。

子代理强制执行 (SUPERVISOR_DELEGATION_ENFORCEMENT,SUPERVISOR_EVAL_ESCALATION_THRESHOLD)

SUPERVISOR_DELEGATION_ENFORCEMENT=true：启用此功能后，当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或执行命令时，立即报错，提示某个钩子脚本执行失败。
排查步骤：
1. 检查钩子脚本是否有执行权限：ls -la /path/to/your/project/.claude/hooks/。确保所有.sh文件有x权限。如果没有，运行chmod +x /path/to/your/project/.claude/hooks/*.sh。
2. 检查监督服务器是否在运行：curl http://localhost:3847/api/state。如果无响应，启动服务器。
3. 检查项目中的.claude/settings.json，确认CLAUDE_SUPERVISOR_URL指向正确的服务器地址和端口。
4. 手动测试钩子连接：在项目目录下，尝试运行CLAUDE_SUPERVISOR_URL=http://localhost:3847 ./claude/hooks/pre-tool-use.sh '{\"tool_name\":\"bash\", \"tool_input\":\"ls -la\"}'。观察输出和错误信息。

问题2：AI评估速度非常慢，每次工具调用都要等好几秒

症状：即使是简单的ls命令，也需要等待较长时间才有响应。
可能原因及解决：
1. Ollama模型未加载：首次使用某个模型时，Ollama需要从磁盘加载，会非常慢。确保Ollama服务已启动，并且你指定的模型已通过ollama pull下载。可以通过ollama list查看已下载模型。
2. Ollama服务响应慢：检查Ollama服务资源占用。如果机器内存不足，推理会变慢。考虑换用更小的模型（如llama3.2:3b）。
3. 网络问题（回退到Claude CLI时）：如果Ollama不可用，系统会回退到claude -p，这需要网络请求到Anthropic API，受网络延迟影响。确保网络通畅，且Claude CLI已认证。
4. 动态规则未生效：频繁执行的命令应该被动态规则捕获。检查logs/eval-history.jsonl是否在增长，并手动运行node scripts/eval-housekeeping.js来生成规则。

问题3：Web终端无法启动或立即断开

症状：在仪表盘点击“+ New”创建终端，标签页一闪而过，或者显示“Session exited”。
排查步骤：
1. 检查dtach是否安装：which dtach。
2. 检查CLAUDE_BINARY环境变量指向的路径是否正确。默认是~/.local/bin/claude，但你的安装路径可能不同。可以在服务器启动前设置CLAUDE_BINARY=/usr/local/bin/claude。
3. 查看服务器日志：journalctl -u claude-supervisor@3847 -f（如果使用systemd）或直接看启动服务器的终端输出，寻找关于spawn PTY失败的错误信息。
4. 确保运行服务器的用户有权限在SUPERVISOR_DTACH_DIR（默认/tmp）目录下创建socket文件。

问题4：PII擦除似乎没有生效，真实IP仍出现在Claude的回复中

症状：启用了PII擦除（MCP路径），但Claude在分析日志时仍然提到了真实的IP地址192.168.1.100。
可能原因：
1. 路径选择错误：如果你用的是Max/Pro计划，却选择了API代理路径，那是无效的，因为API流量不经过你。必须选择MCP路径。
2. MCP服务器未成功连接：在Claude Code的MCP服务器设置中，检查是否添加了claude-supervisor提供的MCP服务器地址（通常是http://localhost:3847/mcp）。在Claude Code中，你可以通过快捷键（通常是Cmd/Ctrl + Shift + P，输入“MCP”）来查看和管理MCP服务器连接。
3. PII类型未匹配：擦除规则基于正则表达式。某些非标准格式的IP（如192.168.001.100）可能无法被默认规则捕获。你可以通过仪表盘的PII Scrubbing面板，临时开启“调试日志”，查看具体哪些文本被匹配和替换了。

问题5：/skills命令在Claude会话中不显示或无法使用

症状：在受监督的Claude Code会话中输入/，没有弹出技能列表，或者提示“未知命令”。
解决：
1. 确保项目的CLAUDE.md文件已正确更新。setup-project.sh脚本会处理这个。你可以检查项目根目录下的CLAUDE.md文件，开头部分应该包含从CLAUDE.md.template注入的技能说明。
2. 重启Claude Code会话。有时Claude Code需要重新加载CLAUDE.md才能识别新技能。
3. 检查监督服务器的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承担更多常规工作，而你则专注于处理那些真正复杂、高风险的决策点。这种渐进式的信任建立过程，才是人机协作的安全之道。

查看全文

http://www.jsqmd.com/news/742572/