源目标和`scripts/install-dev.sh`是开发工具，而不是升级路径。直接安装目标拒绝覆盖由发布版管理的安装或由其他检出拥有的安装。`make all`是明确的开发者机器重装工作流：当已安装的CLI正好指向当前检出时，它可能会回收无标记或先前发布版本的源状态，并在重建后记录严格的所有权标记。这可以对开发者状态运行当前检出的迁移，绝不能用作发布升级。发布版管理的安装必须使用发布版拥有的`scripts/upgrade.sh`或`scripts/upgrade.ps1`解析器。`make install`、`make dev-install`和`scripts/install-dev.sh`是用于全新或隔离开发环境的下层严格管道；它们不是正常的重复开发命令。

### 通过发布脚本安装```bash
VERSION=0.8.6
INSTALL_URL="https://raw.githubusercontent.com/cisco-ai-defense/defenseclaw/${VERSION}/scripts/install.sh"
curl -LsSf "$INSTALL_URL" | VERSION="$VERSION" bash
defenseclaw init --enable-guardrail

在调优时以观察模式运行 guardrail：```bash
defenseclaw setup guardrail --mode observe --restart

请参阅 [docs/QUICKSTART.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs/QUICKSTART.md) 获取完整教程。

---

## 架构

| 组件 | 运行环境 | 角色 |
|-----------|---------|------|
| Python CLI | Python | 操作命令、扫描器编排、配置设置、本地包 |
| 网关边车 | Go | REST API、WebSocket 桥接、策略引擎、护栏代理、审计存储、遥测 |
| OpenClaw 插件 | TypeScript | 请求拦截、工具调用检查钩子、斜杠命令、边车集成 |
| 策略 | YAML/Rego | 准入决策、护栏动作、沙箱/防火墙行为、扫描器配置文件 |
| 文档 | Markdown/JSON | 集中文档、包本地 README 以及 DeepWiki 配置 |

网关为 CLI 和插件暴露本地 REST API，通过 WebSocket 连接到 OpenClaw，通过本地代理检查 LLM 流量，并在持久化审计存储中记录决策。```text
Agent runtime -> OpenClaw plugin -> DefenseClaw gateway -> policy + scanners + audit
                                    |
                                    +-> guardrail proxy -> LLM provider
                                    +-> OTLP / Splunk / webhooks / JSONL

该默认设置会收集所有已注册的日志、追踪和指标，并在本地 SQLite 中保留每一条未经脱敏的日志。在添加目标之前，不会执行任何远程导出。已启用的目标若未设置 `send` 或 `routes`，则接收其支持的每种类型的全部桶和全部信号（未脱敏）：通用 OTLP 接收日志/追踪/指标，Splunk HEC 接收日志，Prometheus 接收指标，Galileo 预设接收追踪。多个目标将收到独立的副本。

使用以下命令查看展开的策略及未脱敏的支路：```bash
defenseclaw config show --effective --section observability
defenseclaw observability plan

不要在一次验证失败后重新启动。恢复私有备份，纠正源文件并重新验证。全局或存储桶隐去配置也适用于生成的本地SQLite投影。要在保留完整本地历史的同时仅隐去远程信任边界，请将全局/存储桶配置设置为`none`，并在该远程目标上设置`send.redaction_profile`或路由配置。

开始本地可观测性，使用：```bash
defenseclaw setup local-observability up
defenseclaw-gateway start
defenseclaw setup local-observability status

请参见 [docs/OBSERVABILITY.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs/OBSERVABILITY.md)、[Galileo 指南](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs-site/content/docs/observability/galileo.mdx) 和 [schema 所有权映射](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/schemas/README.md)。Splunk 特定的设置位于 [docs/SPLUNK_APP.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs/SPLUNK_APP.md)。

每个受支持的现有 POSIX 安装，包括已经运行在 `0.8.4` 上的安装，都会以最新模式通过经过身份验证的目标版本 `defenseclaw-upgrade.sh` 资产跨越 `0.8.5` 硬切割，无需版本覆盖。不可变的 `0.8.4` 内置解析器无法接受其 Windows 桥接矩阵为空的那个真实目标清单。请勿执行由冻结的内置 CLI 印出的任何过时的原始网络提示。由版本拥有的解析器将 `source → 0.8.4 bridge → fresh 0.8.4 controller → 0.8.5 hard cut` 作为一个事务执行。该迁移会备份并原子化地转换配置，保留更窄的路由/编辑行为以及 root/subagent Agent360 兼容性，刷新拥有的本地仪表板而不重置卷，并且永远不需要单独的 apply 命令。请参见 [CLI 参考 — upgrade](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs/CLI.md#upgrade) 了解经过身份验证的解析器引导程序。

对于 Splunk Observability Cloud，请使用位于 [bundles/splunk_o11y_dashboards/README.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/bundles/splunk_o11y_dashboards/README.md) 的仪表板包：```bash
defenseclaw setup splunk dashboards apply \
  --api-url <api-endpoint> \
  --o11y-api-token <api-access-token> \
  --with-detectors \
  --enable-detectors \
  --yes

专注的测试和开发指南位于 [docs/TESTING.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs/TESTING.md) 和 [docs/CONTRIBUTING.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs/CONTRIBUTING.md) 中。

---

## 贡献

欢迎贡献。从 [CONTRIBUTING.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/CONTRIBUTING.md)、[docs/CONTRIBUTING.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs/CONTRIBUTING.md) 以及您要修改领域的专注文档开始。

## 安全

请通过 [SECURITY.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/SECURITY.md) 中描述的流程报告漏洞。

## 许可证

Apache 2.0 - 见 [LICENSE](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/LICENSE)。

版权 2026 Cisco Systems, Inc. 及其附属公司。