Ogment CLI 技能

通过 Ogment CLI 安全地调用 MCP 工具。通过 Ogment 的治理层访问您连接的 SaaS 工具（Linear、Notion、Gmail、PostHog 等）。

---

快速入门（首次使用）

首次使用 Ogment 与用户时，请遵循以下流程：

步骤 1：检查认证状态

ogment auth status

• 如果 loggedIn: true → 跳至步骤 3
• 如果 loggedIn: false → 继续步骤 2

步骤 2：登录（如有需要）

ogment auth login

从响应中提取代码并发送给您的用户。

⚠️ 确保链接可点击！ 使用 markdown 或完整 URL，以便用户可以直接点击。

🔐 批准此代码以连接 Ogment：XXXX-XXXX 👉 dashboard.ogment.ai/cli/approve

等待批准，然后使用 ogment auth status 进行验证。

步骤 3：发现可用内容

ogment catalog

然后针对每个服务器：

ogment catalog <serverId> | jq '[.data.tools[].name]'

步骤 4：向您的用户总结

告诉他们您发现了什么：

✅ 已连接到 Ogment！ 以下是我可以访问的内容：

• Linear: 28 个工具（问题、项目、团队、文档）
• Gmail: 11 个工具（消息、线程、草稿）
• Notion: 5 个工具（搜索、获取、评论）
• Slack: 7 个工具（对话、用户）

您希望我帮助您做什么？

---

先决条件

首次设置（登录流程）

⚠️ 重要提示，适用于代理（AGENTS）： 不要告知人类用户运行 ogment auth login — 你需要自行运行该命令并发送生成的代码给他们！

步骤 1：检查是否已认证

ogment auth status

若结果显示 loggedIn: true，则跳至核心工作流程。

步骤 2：若未登录，启动设备流程

ogment auth login

此命令将返回包含设备代码的 JSON。提取并发送给人类用户：

示例输出：

{
  "data": {
    "event": "auth_login.pending",
    "verification": {
      "userCode": "ABCD-1234",
      "verificationUri": "https://dashboard.ogment.ai/cli/approve"
    }
  }
}

步骤 3：将代码发送给你的用户

告知他们：

请批准此代码：ABCD-1234 👉 https://dashboard.ogment.ai/cli/approve

步骤 4：等待批准

一旦获得批准，ogment auth login 命令将自动完成。然后验证：

ogment auth status

认证与凭证

• 凭证存储位置： ~/.config/ogment/credentials.json
• Token 管理： Ogment 负责处理所有连接服务的 OAuth 流程
• 权限范围： 访问权限取决于你在 Ogment 仪表盘 中连接的服务
• 每位代理的权限： 每个代理仅能看到你明确授权的工具

本技能中未存储任何凭证 —— 所有认证均由 Ogment CLI 管理。

使用场景

• 用户要求与其连接的服务（如 issue、文档、邮件、分析）进行交互
• 需要调用要求认证/凭证的 MCP 工具
• 发现用户已集成的服务

核心工作流

状态检查 → 目录查询 → 服务器目录 → 工具目录 → 调用执行

1. 检查连接性（当怀疑存在问题时）

ogment status

返回认证状态、连接性和可用服务器列表。检查 summary.status 可快速了解系统健康状况。

2. 发现服务器

ogment catalog

返回包含 serverId 和 toolCount 的服务器列表。后续调用需使用 serverId。

3. 列出服务器上的工具

ogment catalog <serverId>

返回所有工具的 name 和 description。通过描述信息定位所需工具。

4. 查看工具结构

ogment catalog <serverId> <toolName>

返回包含属性、类型、必填字段和描述的 inputSchema。

5. 调用工具

ogment invoke <serverId>/<toolName> --input '<json>'

输入方式：

• 内联JSON：--input '{"query": "test"}'
• 文件输入：--input @path/to/input.json
• 标准输入：echo '{}' | ogment invoke ... --input -

6. 调试错误

ogment invoke <serverId>/<toolName> --input '{}' --debug

--debug 标志会显示原始 MCP 错误信息及字段级验证详情。

安全注意事项

文件输入安全

--input @path 会读取本地文件。避免以下路径：

• ~/.ssh/* — SSH密钥
• ~/.aws/* — AWS凭证
• ~/.config/ — 应用配置和令牌
• ~/.bash_history, ~/.zsh_history — Shell历史记录
• 浏览器配置文件目录

最佳实践： 仅对专门为此创建的文件使用 --input @path

网络安全

• 所有 API 调用均通过 dashboard.ogment.ai 路由
• 不直接连接 SaaS API
• 传输层使用 TLS 加密

权限模型

• 工具权限在 Ogment 仪表盘中按 agent 划分
• Agent 仅能查看被授予访问权限的工具
• 写入操作可能受 agent 权限限制

输出格式

所有命令均返回结构化的 JSON：

{
  "ok": true,
  "data": { ... },
  "error": null,
  "meta": { "command": "..." },
  "next_actions": [
    { "command": "...", "title": "...", "reason": "..." }
  ]
}

• 首先检查 ok — 布尔型成功指示器
• next_actions — 建议的后续命令
• error.category — validation、not_found、remote、auth、internal
• error.retryable — 重试是否可能有帮助

常见模式

根据意图查找工具

ogment catalog <serverId> | jq '.data.tools[] | select(.name + .description | test("email"; "i"))'

列出分配给用户的问题

ogment invoke openclaw/Linear_list_issues --input '{"assignee": "me"}'

搜索 Notion

ogment invoke openclaw/Notion_notion-search --input '{"query": "quarterly review", "query_type": "internal"}'

获取 Gmail 消息

ogment invoke openclaw/gmail_listMessages --input '{"q": "is:unread", "maxResults": 10}'

错误恢复

处理过期的连接

当您收到 HTTP_401 并附带如下消息时：

"您与 [Service] 的连接已过期。请重新连接..."

通知您的人工（附带可点击链接）：

⚠️ 您的 [Service] 连接已过期。 请在此处重新连接：dashboard.ogment.ai （前往 Integrations → [Service] → Reconnect）

完成后请告诉我，我将重试！

权限缺失处理

若所需工具不可用（如目录中无 gmail_createDraft）：

• 此属正常现象 —— 代理权限存在范围限制
• 写入工具可能默认处于禁用状态

向人类用户提示（附带可点击链接）：

我暂无 [服务名称] 的写入权限 请前往 dashboard.ogment.ai (代理 → [代理名称] → 权限设置) 开启

配置完成后请告知，我将重新检测！

退出代码表

参数标志参考

避免使用： --quiet（将抑制包括数据在内的所有输出）

执行前检查清单

调用工具前需确认：

1. ✅ 服务端存在（catalog 指令验证）
2. ✅ 工具存在（catalog <服务端> 验证）
3. ✅ 检查架构中的必填字段
4. ✅ 类型严格匹配（数字/字符串区分）
5. ✅ 使用精确的ID大小写
6. ✅ 若使用 --input @路径，确保文件不含敏感数据