核心用法
OpenClaw AICFO Agent 为 OpenClaw 提供了一条纯服务端、无浏览器依赖的 AICFO 平台接入通道。用户仅需配置 AICFO_API_KEY 环境变量，即可通过本地 Node 脚本 bin/openclaw-aicfo-adapter.mjs 完成全部操作。
关键流程三步走：
1. 会话自省 (session) —— 获取 granted scopes、implicitCompanyId 及可访问公司列表
2. 公司范围解析 —— 优先使用 UUID，否则使用 slug 或精确公司名
3. 业务操作 —— 通过适配器调用 dashboard、query、search、get-entity、get-file、connectors、documents 等命令
技术架构特点：
- REST-first 设计，不依赖 MCP SDK 或本地 npm 包
- 自包含 skill 包，仅需 Node 运行环境
- 明确区分机器连接器表面 (
/api/agent/connectors) 与遗留浏览器路由
显著优点
| 优势 | 说明 |
|------|------|
极简部署 | 单一环境变量 + Node 即可运行，无需复杂依赖链 |
| **权限透明** | 会话端点实时返回 key 的 granted scopes，操作前可知边界 |
| **公司隔离清晰** | 支持多租户场景，implicitCompanyId 或显式选择确保数据范围可控 |
| **连接器生态** | 支持 Telegram、Google Drive 等连接器操作，可扩展性强 |
| **文档智能** | 内置 document-questions 与 answer-document-questions，支持 RAG 流程 |
潜在缺点与局限性
- UUID 依赖：公司选择逻辑要求理解 session 返回结构，无 UUID 时需回退到 slug/名称匹配
- 作用域硬性限制：若 key 缺少
documents.write或特定 connector-use scope，对应操作将失败，需提前校验 - 异步处理不确定性：文档上传后需轮询
document-questions确认处理完成，无实时回调机制 - Node 运行时绑定：虽轻量，但仍要求目标环境预装 Node，纯容器/无运行时场景受限
适合人群
- 需要将 AICFO 企业数据集成到自动化工作流（CI/CD、定时任务）的平台工程师
- 构建内部数据代理、报告生成系统的AI 应用开发者
- 希望避免浏览器 OAuth 流程、追求纯 API 驱动集成的企业 IT 团队
常规风险
| 风险类别 | 具体表现 | 缓解建议 |
|----------|----------|----------|
| **密钥泄露** | `AICFO_API_KEY` 为 Bearer Token，泄露即等于账号权限暴露 | 存入 secrets manager，禁止硬编码 |
| **越权访问** | 忽略 `requiresCompanySelection` 可能误操作非授权公司数据 | 严格遵循 Bootstrap 流程，显式传递 company_id |
| **作用域误判** | 未校验 scopes 直接调用连接器或文档写操作 | 操作前必检 session.grantedScopes |
| **遗留路由误用** | 误将 `/api/connections/*` 当作机器端点 | 仅使用 `/api/agent/*` 系列端点 |
| **文档处理竞态** | 上传后立即查询可能拿到未就绪状态 | 实现指数退避轮询 document-questions |
验证清单（建议执行）
1. node bin/openclaw-aicfo-adapter.mjs session —— 确认 key 有效及作用域
2. node bin/openclaw-aicfo-adapter.mjs tools —— 列示可用工具
3. dashboard 或 query 读操作 —— 验证公司级数据访问
4. 连接器探活（如 telegram list_chats）—— 确认外部系统集成能力