通过 Agent 使用 BPMAX CLI
bpmax-cli 是 OpenClaw、Codex 等 Agent 操作 BPMAX 的受控执行层。普通用户不需要记住大量命令、模板 ID 或请求结构，只需要说明业务目标、目标环境和允许执行的范围，由 Agent 读取对应 Skill、通过受控命令完成操作、展示变化并在高风险操作前停下来确认。
如果你要把接入规范直接交给 Agent，请让它在安装 CLI 前先读取 Agent 首次接入执行契约。该页面主要写给 Agent，不是普通用户操作手册。
最简单的开始方式
把下面这段话直接发送给当前使用的 Agent：
请先完整阅读下面的 Agent 接入执行契约：
https://doc.bpmax.cn/develop/bpmax-cli/agent-quickstart.html
阅读完成后，按照该契约安装并初始化最新版 beta 的 bpmax-cli，连接这个 BPMAX 环境：
<粘贴 BPMAX 页面地址>你通常只需要完成三件事：
- 提供 BPMAX 页面地址。
- 打开 Agent 返回的授权链接并确认验证码。
- 第一次修改配置时，确认用于存放 sysconfig 配置库的本地目录；之后在 Agent 提交配置、创建项目或推进审批前确认最终差异。
授权成功只代表 Agent 可以访问 BPMAX。要修改流程、表单、列表等配置，还需要先初始化本地配置目录并进入该目录工作。这个目录是本地 sysconfig 配置库，不是 BPMAX 页面地址中的 w:xxx 业务工作区。
不同 Agent 运行环境
bpmax-cli 同时适用于 OpenClaw 这类长期运行的服务型 Agent，以及本地桌面或终端 Agent：
| 运行环境 | 典型场景 | 接入要求 |
|---|---|---|
| OpenClaw | 在飞书等渠道持续响应多个用户，执行查询、配置、审批和业务 Skill | 使用 --agent openclaw；从租户、channel、用户或会话元数据生成可信 profile-scope，每个用户上下文必须隔离 |
| 本地桌面或终端 Agent | 在当前项目目录中完成一次实施、开发、配置或测试任务 | 使用实际 Agent adapter；保留 init 返回的 profile 和 config-dir，不复用其他任务的授权状态 |
无论运行在哪种 Agent 中，配置写入、安全确认和 E2E 证据要求一致。OpenClaw 不能因为是后台长期运行服务而共享用户 profile、跳过确认或绕过 Skill gate。
我想做什么
| 目标 | 可以直接对 Agent 说 | 详细说明 |
|---|---|---|
| 初始化新环境 | “请先阅读 Agent 首次接入执行契约，再连接这个 BPMAX 地址：<地址>。” | Agent 首次接入执行契约 |
| 初始化本地配置目录 | “请为当前环境初始化本地配置目录，完成后告诉我目录位置。” | 通过 Agent 修改 BPMAX 配置 |
| 配置流程或模板 | “请在采购申请流程中增加规则：金额超过 50 万时由财务总监审批。” | 通过 Agent 修改 BPMAX 配置 |
| 创建流程应用 | “请为供应商准入创建完整流程应用。” | 通过 Agent 修改 BPMAX 配置 |
| 创建流程单 | “请为武汉研发中心创建一条 30 万元的设备采购申请。” | 能力与场景索引 |
| 处理审批 | “请处理项目 <项目编号> 的当前待办，先告诉我有哪些操作。” | 能力与场景索引 |
| 编写实施任务书 | “先为这次 BPMAX 改造生成任务书，不要直接执行。” | Agent 工程化用法 |
| 真实回归测试 | “请重新运行采购申请完整测试。” | E2E 测试与证据 |
| 使用业务 Skill | “请创建一条采购申请。” | BPMAX Business Skill |
| 排查审批矩阵 | “请检查项目 <项目编号> 为什么没有找到审批人。” | Agent 工程化用法 |
| 报告 CLI 缺陷 | “这个问题看起来是 bpmax-cli 的缺陷，请确认并整理问题草稿。” | Agent 工程化用法 |
完整命令组与场景映射见 能力与场景索引。
人、Agent、CLI 与平台的职责
人类用户
- 说明业务目标、目标环境、对象名称和验收口径。
- 判断哪些变化属于本次需求。
- 确认准备修改的内容、最终提交变化和真实状态变更。
- 提供真实业务测试数据，不能只写无意义的测试值。
OpenClaw、Codex 等 Agent
- 识别并读取正确的 BPMAX Skill。
- 通过 memory、线上 readback 和 capability 获取上下文。
- 将自然语言需求转换为受控 CLI 操作。
- 在配置提交、项目创建、审批推进和删除前停止并请求确认。
- 汇报真实执行状态，不把 dry-run、接口诊断或旧截图说成完成。
bpmax-cli
- 隔离 profile 和本地 Agent 状态。
- 执行服务端 capability、终端治理和审计检查。
- 为配置提供 export、lint、build、submit、verify/readback 闭环。
- 在配置命令执行前自动识别当前本地 sysconfig 目录，并核对它与当前 profile 的初始化绑定；目录错误时在读取 work 或请求平台前停止。
- 为审批和 E2E 提供结构化上下文、证据与安全门禁。
BPMAX 平台
- 保存真实流程、模板、项目和权限状态。
- 执行最终权限校验和业务逻辑。
- 提供真实用户页面，用于创建页、选择器、自动回填和 E2E 验收。
配置与测试的边界
- BPMAX 配置必须通过 CLI 的受控配置能力完成，不能让 Agent 直接修改本地
think_*镜像，也不能通过浏览器页面保存配置。 - 配置命令必须在已初始化的本地 sysconfig 根目录或其子目录中执行。用户无需在每次提示词中要求“检查当前目录”，CLI 会自动阻断普通代码仓库、错误 profile 或错误环境目录。
- 浏览器主要用于授权和真实 E2E 验收，不用于绕过配置 Skill 或 CLI 安全检查。
- 项目创建遇到人员、项目、预算、子表等复杂控件时，可以由 CLI 生成 handoff，再让 Agent 在真实页面完成选择和提交。
- 正式 E2E 必须按照已审核的测试用例和本轮执行记录推进，每一步都保存本轮证据。
典型配置对话
第一次让 Agent 分析：
请在采购申请流程中增加规则：金额超过 50 万时由财务总监审批。
先不要提交。确认修改范围后：
刚才列出的修改范围已确认。请准备最终提交内容，仍然不要提交。最终确认：
确认提交。提交后重新读取线上结果并打开真实运行页面验收，是配置 Skill 的默认要求，用户无需在确认语句中重复说明。
典型测试对话
请重新运行采购申请的完整测试。测试最终结果需要明确区分：
- 已更新测试资产。
- 已执行接口诊断。
- 已执行真实浏览器回归。
- 已完成并通过全部必需步骤。
安装与更新
推荐让 Agent 负责安装：
请把 bpmax-cli 更新到最新可用版本，并告诉我更新结果。高级用户也可以在终端执行：
npm i -g bpmax-cli@beta
bpmax-cli --version
bpmax-cli updateAgent 场景必须保留 init 返回的 --config-dir <config_dir> 和真实 --profile <profile>。不要从自然语言中猜 profile，也不要在共享 Agent runtime 中复用默认 ~/.bpmax。
安全确认规则
以下动作必须先展示计划或 dry-run，再由用户确认：
- 提交、创建、删除 BPMAX 配置。
- 全量替换 workspace-flow 或导航配置。
- 创建真实项目或推进审批环节。
- 批量写入、发布数据集或矩阵规则。
- 创建 GitLab issue。
只读 export、inspect、context、actions、requirements、readback 和 lint 通常不需要额外确认。
文档导航
当前文档基线
本文档覆盖 bpmax-cli 0.2.1-beta.25 的公开能力。历史版本变化见 系统更新说明。