核心用法
Ogment CLI 是一款企业级 MCP 工具网关，允许 AI Agent 在统一治理框架下安全调用用户授权的 SaaS 服务。核心工作流遵循 status → catalog → catalog <server> → catalog <server> <tool> → invoke 的渐进式发现模式，支持从服务枚举、工具清单获取到最终调用的完整链路。
认证机制采用 OAuth 2.0 设备码流程：Agent 执行 ogment auth login 生成一次性验证码，用户需在 dashboard.ogment.ai/cli/approve 完成人工授权，全程无需暴露凭据给 Agent。凭证存储于 ~/.config/ogment/credentials.json，由 CLI 自动管理刷新。
工具调用通过 ogment invoke <serverId> <toolName> --input '<json>' 执行，支持 --debug 获取原始 MCP 错误诊断，--example 生成参数模板。输出为结构化 JSON，包含 ok 状态、next_actions 建议操作及错误分类（validation/not_found/remote/auth/internal）。
显著优点
1. 统一治理层：所有 SaaS API 调用路由至 Ogment 云端，避免直接暴露服务凭证，支持 TLS 全链路加密与细粒度审计
2. 权限最小化：Per-agent 权限模型，管理员可在控制台精确控制每个 Agent 可见的工具集（如仅开放 Gmail 读权限，禁用写操作）
3. 渐进式发现：从服务目录到工具 Schema 再到示例参数的分层探索，降低 Agent 调用未知 API 的风险
4. 错误可观测：标准化的错误分类（HTTP_401 表服务连接过期、VALIDATION_INVALID_INPUT 表参数错误）与可操作建议，支持自动化重试决策
潜在缺点与局限性
- 人工阻塞点：设备码授权需用户实时介入，无法实现完全自动化流程
- 网络依赖：所有调用必须经由 dashboard.ogment.ai，离线或网络隔离环境不可用
- 服务商绑定：新增 SaaS 集成取决于 Ogment 官方支持节奏，非 MCP 生态的自定义工具无法接入
- 延迟开销：代理层增加单跳网络延迟，高频低延迟场景可能不适用
- 权限盲区：Agent 无法自助申请权限扩展，需人工登录控制台修改，中断工作流
适合人群
- 企业安全团队：需要将 AI Agent 的 SaaS 访问纳入统一 IAM 与审计体系
- 多 SaaS 用户：同时使用 Linear、Notion、Gmail、PostHog 等工具，希望避免重复配置 OAuth
- 合规敏感场景：金融、医疗等行业需满足最小权限原则与操作留痕要求
- Agent 开发者：构建需要调用外部 API 的工作流，但不愿自行处理各平台的认证逻辑
常规风险
| 风险类别 | 描述 | 缓解措施 |
|---------|------|---------|
| 会话劫持 | 设备码有效期内被第三方截获 | 验证码有效期极短，且需用户主动在已登录会话中确认 |
| 权限提升 | 管理员误配置导致 Agent 获得过度授权 | 定期审计 dashboard 中的 Agent 权限矩阵 |
| 服务可用性 | Ogment 网关故障导致全部工具不可用 | 关键路径应设计降级策略或本地缓存 |
| 数据驻留 | SaaS 数据经 Ogment 云端中转 | 评估 Ogment 的 SOC 2/ISO 27001 认证状态与数据处理协议 |
| 凭证泄露 | `~/.config/ogment/credentials.json` 被非授权读取 | 确保文件权限为 0600，避免容器镜像残留 |
使用建议
首次 onboarding 时严格遵循文档的 4 步流程：检查认证状态 → 启动登录流程 → 发送可点击链接给用户 → 发现可用工具并汇总告知。避免让用户自行执行 ogment auth login，这会破坏设备码流程的安全设计。