halofy

这是什么？适合谁？

Halofy（halofyai/halofy）是一个企业级 AI Agent 治理层。它解决多 Agent 在企业环境中部署时的核心问题：谁有权调用哪个 Agent？Agent 做了什么？如何审计？

核心价值：不是又一个 Agent 框架，而是给已有的 Agent（无论 Claude Code、Codex、还是自定义 Agent）加一层「统一身份 + 权限控制 + 审计日志」的治理层。

适合人群：

• 企业 IT 安全团队：需要管控员工使用 AI Agent 的权限
• 平台工程团队：需要将多 Agent 统一接入企业基础设施
• 合规团队：需要审计所有 Agent 的操作记录
• 构建 Agent 市场的平台方

不适合：个人开发者使用单个 Agent（直接用 Agent 原生的 auth 即可）；不需要权限管控的小团队。

使用前提：企业身份系统（LDAP / OIDC / SAML）；至少一个 AI Agent 需要接入；PostgreSQL 数据库（存储审计日志）。

准备工作

1. Halofy 部署：Docker Compose 或 Kubernetes 部署
2. 身份系统：接入企业 SSO（支持 OIDC / SAML / LDAP）
3. 数据库：PostgreSQL 14+（存储策略和审计日志）
4. Agent 注册：将需要治理的 Agent 注册到 Halofy
5. 成本：Halofy 开源免费（Apache 2.0）；运行成本 = 服务器 + 数据库
6. 时间预算：基础部署 30 分钟；完整接入企业 SSO 和 Agent 约 2 小时

快速上手（3 步）

第一步：部署 Halofy

git clone https://github.com/halofyai/halofy.git
cd halofy
docker compose up -d

第二步：配置身份源

编辑 config/identity.yaml：

identity:
  provider: oidc
  oidc:
    issuer: https://auth.company.com
    client_id: halofy
    client_secret: ${OIDC_CLIENT_SECRET}

第三步：注册 Agent

curl -X POST http://localhost:8080/api/v1/agents \
  -H "Authorization: Bearer ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "code-review-agent",
    "type": "claude-code",
    "allowed_scopes": ["repo:read", "pr:comment"]
  }'

初级用法

权限策略

定义 Agent 能做什么、不能做什么：

# policy.yaml
policies:
  - name: "code-review-only"
    agent: "code-review-agent"
    allow:
      - "repo:read"
      - "pr:comment"
    deny:
      - "repo:write"
      - "deploy:*"

审计日志

所有 Agent 操作自动记录：

# 查询某个 Agent 的操作记录
curl http://localhost:8080/api/v1/audit?agent=code-review-agent&from=2026-08-01

高级玩法

多 Agent 角色管理

将 Agent 按角色分组，统一管理权限：

roles:
  - name: "security-auditors"
    agents: ["vuln-scan-agent", "compliance-check-agent"]
    permissions: ["security:*", "audit:read"]

API 网关集成

将 Halofy 作为 API 网关插件，所有 Agent 调用自动经过治理层：

# nginx/apisix 配置示例
plugins:
  - name: halofy-auth
    config:
      endpoint: http://halofy:8080/verify
      cache_ttl: 300

合规报告

自动生成 Agent 活动合规报告：

halofy report --type compliance --from 2026-08-01 --to 2026-08-26 --format pdf

小技巧

1. 策略最小化：从 deny-all 开始，逐步添加 allow 规则，避免权限过度开放
2. 审计保留：设置审计日志保留 90 天以上，满足 SOX/ISO 27001 等合规要求
3. Agent 命名规范：使用统一命名规则（如 team-purpose-agent），便于策略管理
4. 告警规则：配置异常行为告警（如 Agent 尝试访问 deny 列表中的资源）
5. 定期复盘：每月审查 Agent 权限，移除不再需要的 Agent

常见踩坑

踩坑 1：SSO 集成失败

现象：登录后无限重定向

原因：OIDC callback URL 配置错误

解决：确保 redirect_uri 与 Halofy 配置一致；检查 OIDC provider 的 allowed origins

踩坑 2：Agent 调用被误拦截

现象：合法 Agent 操作被权限策略拒绝

原因：权限策略过于严格，或 Agent 注册时 scope 配置不完整

解决：检查审计日志中的拒绝原因；在 policy.allow 中添加缺失的 scope

踩坑 3：数据库性能问题

现象：审计查询变慢，影响 Agent 调用延迟

原因：审计日志表未建立索引，或日志量过大

解决：为 agent_id、timestamp 建立索引；设置日志保留策略自动清理旧数据

踩坑 4：多 Agent 冲突

现象：两个 Agent 同时操作同一资源导致冲突

原因：Halofy 的权限控制不包含资源级锁

解决：在 Agent 编排层实现乐观锁；或使用 Halofy 的 resource:lock scope

踩坑 5：Agent 绕过治理层

现象：Agent 直接调用 API 绕过 Halofy

原因：网络层面未强制所有流量经过 Halofy

解决：在 API 网关层强制所有 Agent 流量经过 Halofy 验证；使用 Kubernetes NetworkPolicy 隔离 Agent 网络

常见问题 FAQ

Q1: Halofy 和 API Gateway 有什么区别？

A: API Gateway 管理服务间的 API 调用，Halofy 管理 AI Agent 的权限和审计。Halofy 可以集成到 API Gateway 中，但它的策略模型是 Agent 感知的（理解 Agent 的 scope 和操作语义），而传统 API Gateway 只理解 HTTP 方法和路径。

Q2: 支持哪些 AI Agent 框架？

A: 任何支持自定义认证头的 Agent 框架都可以接入 Halofy。官方提供 Claude Code、Codex 和 LangChain 的接入示例。

Q3: 审计日志会记录 Agent 的具体对话内容吗？

A: 默认只记录操作元数据（谁、何时、做了什么操作）。可选择开启「详细审计」模式记录完整对话，但会增加存储成本。

Q4: 开源版和企业版有什么区别？

A: 核心治理功能完全开源（Apache 2.0）。企业版提供高级合规报告、SSO 高级集成、SLA 支持。

Q5: 性能开销如何？

A: Halofy 在 Agent 调用路径上增加约 5-10ms 延迟（权限验证 + 审计写入）。对于大多数 Agent 调用场景（秒级响应），几乎无感知。

进阶学习建议

掌握 Halofy 基础治理后，建议深入：

1. 零信任 Agent 架构：结合 agent-safe-pipeline（人机审批工作流）和 Halofy，构建「Agent 提议 → 权限验证 → 人类审批 → 审计记录」的完整零信任 Agent 执行链路。
2. Agent 身份全栈：Halofy（治理）+ sv-number MCP（手机号）+ Sentio（邮箱）构成 Agent 的完整数字身份体系——从身份认证到通信到治理的闭环。
3. 合规自动化：将 Halofy 审计日志接入 SIEM 系统（如 Splunk、ELK），实现 Agent 活动的实时监控和自动化合规检查。

参考链接

• 官方仓库
• OIDC 规范
• Apache 2.0 License

最后更新：2026-08-26 · 作者：MagicNetWorld · 基于公开资料整理，AI 辅助生成