ITADN · 发现全球开源项目

每次调用都会经过一个决定其是否执行的 sidecar。
策略输入，签名决策输出。确定性。调用级别。

1. 什么是 OpenFirma？

OpenFirma 是一个运行时执行边界，位于你的 AI 代理与外部世界之间。代理发出的每个出站调用都会经过一个本地 Sidecar，由它决定是否执行：使用你拥有的 Cedar 策略，在本地进行评估，热路径上没有模型。

我们构建它的原因： AI 代理正在成为软件操作员。它们调用 API，读写文件，发送消息并执行代码。这很有用，但也意味着一个糟糕的提示、一个被破坏的依赖项或一个困惑的模型，可能在任何人注意到之前变成真实的出站操作。OpenFirma 为这些操作提供了一个边界。

它的工作原理： 你定义一个策略，说明每个代理被允许做什么。每个出站调用都会经过 Sidecar，它在执行前拦截请求并在本地进行评估。Sidecar 对操作进行分类（例如 code.read、communication.external.send），验证能力令牌，并检查策略。如果为 ALLOW，调用将继续执行，并即时注入凭证。如果为 DENY，调用将被阻止，并写入一个签名的审计事件。执行逻辑位于代理进程之外。

2. 使用 OpenFirma 运行你的编码代理

安装

Linux / macOS:

curl -fsSL https://install.openfirma.ai | sh

在已安装 Homebrew 的 macOS 上，安装程序会自动使用 brew install firma-ai/openfirma/firma。您也可以直接安装：

brew install firma-ai/openfirma/firma

从源码构建和安装（需要 Rust 1.88+ 和 protoc）：

git clone https://github.com/Firma-AI/openfirma
cd openfirma
cargo install --path crates/firma --locked

快速入门

firma 以单个预编译的静态二进制文件形式提供，无需构建工具链或 API 密钥即可开始使用。

启动 OpenFirma 有两种方式。两者最终都会到达相同的状态（你的代理在强制执行下运行），但第一种方式尝试起来更快，第二种方式则提供更多控制权。

选项 A：零配置

firma run 会在会话期间自动启动本地 Authority 和 Sidecar，并在代理退出时将其关闭。只需一条命令，无需任何配置，完成后也不会留下任何运行中的进程。首次启动时会提示一次以确认自动启动；后续运行则静默进行。

firma run -- claude

每个出站呼叫都会经过规范化处理，并与您的 Cedar 策略进行比对，随后被转发或拒绝。在第二个终端中实时查看决策：

firma monitor

选项 B：显式设置

firma sidecar start 将 Authority 和 Sidecar 作为持久守护进程启动，使其在会话之间保持存活。

firma config                       # scaffold once: keys, policy, mappings
firma sidecar start --detach       # boot Authority + Sidecar as persistent daemons
firma run -- claude
firma monitor

当您需要针对同一 Authority 运行多个 agents、在会话之间保持强制执行运行，或在开始任何操作之前使用 firma config 预先配置 posture 和 mappings 时，请使用此功能。

Policies

Cedar 策略文件位于 .firma/policies/ 下。Authority 会监视该目录，并自动将任何更改推送到所有已连接的 Sidecars——编辑文件并保存后，强制执行将在 30 秒内更新。无需重启。

firma policy validate .firma/policies/my-policy.cedar  # check before it goes live
firma policy test     .firma/policies/fixture.toml      # run allow/deny fixtures

Packs

firma config 从 pack 中为你的第一个策略生成脚手架——pack 是姿态（posture）与一个或多个映射（mapping）的预构建组合。姿态定义了默认允许的操作类别。映射将特定服务的原始 HTTP 调用转换为这些操作类别。如果没有针对某服务的映射，Sidecar 将无法对其调用进行分类并将其阻止。

Posture packs，每个项目选择一个：

Posture	允许的内容
`strict`	仅允许 `credential.read` 和 `communication.external.send`。不允许代码操作。
`dev`	增加 `code.read/write`、issues、包安装。不允许支付或破坏性操作。
`dev-with-delete-watch`	`dev` 加上针对 local-exec 和 delete-watch 场景的 `code.destructive`。

Mapping packs，为你代理调用的每个服务添加一个：

Mapping	覆盖范围
`anthropic`	`api.anthropic.com`
`openai`	`api.openai.com`
`github`	GitHub REST + 智能 HTTP → 12 个操作类别
`gmail`	41 个 Gmail REST 端点 → 7 个操作类别
`stripe`	88 个 Stripe REST 端点 → 14 个操作类别
`npm`	`registry.npmjs.org`
`pypi`	`pypi.org`, `files.pythonhosted.org`
`cargo`	`crates.io`

firma policy list                                        # browse all available packs
firma config --posture dev --mapping github --mapping stripe

实时策略更新

随时编辑磁盘上的 Cedar 策略文件。Authority 通过文件监视器捕获更改，并将更新后的 bundle 推送到所有已连接的 Sidecar。无需重启。

完整策略参考：概念：策略 · 编写您的第一个 Cedar 策略

不同的操作模型

Sidecar 位于每个代理进程旁边，并强制执行每个出站调用。Authority 是单一信任根：它颁发能力令牌，并向一个或多个 Sidecar 流式传输策略 bundle。单个 Authority 可以并发管理许多代理；Sidecar 在本地强制执行，而无需在每个请求时回调。

1. 单智能体（类似快速入门）

OpenFirma 首先查找现有的 Authority。如果未配置，则提议为当前会话自动启动本地 Mini Authority 和 Sidecar，封装智能体进程，并自动应用所选的策略配置文件。

firma run -- claude

2. 本地权限，多个代理

权限变为持久化，并在本地代理会话之间共享。每个新的 firma run 都附加到相同的信任根，并拉取当前的策略包，而无需重启现有代理。

firma config
firma sidecar start --detach

firma run -- claude   &
firma run -- codex    &
firma run -- opencode

3. 团队权限，多机器上的代理

每个 Sidecar 在其自身机器上本地执行策略，而共享的 Authority 则在团队中分发策略包、能力令牌和吊销更新。

# On each developer machine or CI runner:
firma run \
  --authority https://authority.internal \
  --profile claude-code \
  -- claude

4. 自定义权限，无需 firma run 的自定义代理
适用于更结构化的企业用例

Sidecar 作为独立的执行代理独立运行。任何遵守 HTTP_PROXY / HTTPS_PROXY 的代理、CI 工作器或自定义运行时，均可在无需 SDK 集成或特定于代理的包装器的情况下进行治理。

firma authority --config firma.toml
firma sidecar   --config firma.toml

export HTTP_PROXY=http://127.0.0.1:8080
export HTTPS_PROXY=http://127.0.0.1:8080
python my_agent.py

Authority 可以是本仓库中包含的 Mini Authority，也可以是您自己实现的 FirmaAuthority gRPC 接口。

CLI 参考

独立命令（仅包含标志，无子命令）

命令	描述
`firma run`	通过 Sidecar 在沙箱中启动一个 agent
`firma config`	脚手架生成新的 agent 配置目录（`--mode…`）
`firma monitor`	跟踪审计决策和组件日志（`--source…`）
`firma doctor`	诊断 Firma 安装
`firma help`	打印任何命令的帮助信息

firma sidecar — 运行和管理强制执行 Sidecar 守护进程。裸形式（无子命令）= 前台服务器。

子命令	描述
`sidecar start`	作为守护进程启动 Sidecar（+ 本地 Authority）
`sidecar stop`	优雅停止守护进程（`--timeout` 回退）
`sidecar status`	列出存活的 Sidecar + 健康状态（表格或 `--json`）

firma authority — 签发令牌，流式传输策略包和吊销。

子命令	描述
`authority revocations`	管理吊销列表（嵌套组）
`authority generate-key`	生成新的 Ed25519 签名密钥对
`authority init-tls`	引导本地 CA + Authority↔Sidecar 证书
`authority issue`	签名并输出能力令牌至 TOML 种子
`authority issue-client-cert`	为 Sidecar 签名 mTLS 客户端证书
`authority generate-client-ca`	生成新的 mTLS 客户端 CA 密钥对

firma policy — 浏览模板目录并验证 Cedar 捆绑包。

子命令	描述
`policy list`	打印所有态势和映射模板
`policy validate`	解析并模式检查 Cedar 策略文件
`policy test`	针对捆绑包运行允许/拒绝测试用例

firma token — 批准和吊销本地执行治理令牌（HITL）。

子命令	描述
`token approve`	批准待处理的治理令牌
`token revoke`	吊销待处理或已批准的治理令牌

完整 CLI 参考：docs/cli.md

3. 架构

Mini Authority: 颁发能力令牌并向已连接的 Sidecar 分发策略包。位于请求路径之外。

Sidecar: 运行在代理进程旁边并拦截出站调用。在执行前本地评估策略并发出签名审计事件。

Audit: 每个强制决策都会生成包含已评估操作、结果和元数据的签名审计记录。

功能

结构化拦截： 所有操作模态均通过 Sidecar 汇聚，以内核沙箱为底线
确定性意图： 每个工具调用都被分类为可强制执行的行动类别；Cedar 对相同输入始终评估出相同决策
逐调用强制： 策略在执行前针对当前策略和累积的会话状态进行评估
JIT 凭证： 联合代理在 ALLOW 时按调用颁发凭证；代理从不持有原始令牌；数据外泄在结构上是不可能的
签名审计： 每个决策都会发出包含策略所见的精确信封的签名执行事件

4. 仓库结构

基础设施


`crates/firma`	CLI 入口点：`firma run`、`firma sidecar`、`firma monitor`、`firma doctor`
`crates/firma-sidecar`	执行 Sidecar：拦截器、流水线、连接器
`crates/firma-authority`	Mini Authority：用于本地开发的基于文件的信任根
`crates/firma-core`	共享类型、Cedar schema、操作类、审计事件格式
`crates/firma-run`	Agent 进程隔离：bwrap 后端、配置文件解析、自动启动
`crates/firma-runtime-state`	运行时路径、pidfile、每次运行的 sidecar 标记、本地存活探针
`crates/firma-stack`	`firma sidecar start` 内部使用的进程监督原语

示例


`examples/demos`	包含三个自包含执行场景的 TUI 演示运行器
`examples/agents`	故意具有风险的演示智能体 (OpenAI Agents SDK + Google ADK)
`examples/e2e`	本地堆栈示例：通过 `HTTP_PROXY` 连接 Authority + Sidecar + 智能体

Docs


`docs/`	架构、CLI 参考、配置参考
`docs-site/`	Astro/Starlight 文档站点

许可证

GPL 3.0。参见 LICENSE