曹操出行开放平台

本地联调：命令行 cop-cli 与本地 AI 助手

如果你习惯命令行，或者要把联调写进脚本，直接装 cop-cli——它自己就能用；本机已有 AI 编程助手的，再装两份技能就是能力最全的形态。三种联调形态的对比见 联调工具与 AI 助手。

安装

# macOS / Linux
curl -fsSL https://open.caocaokeji.cn/asset/cop-cli/install.sh | sh

# Windows PowerShell
irm https://open.caocaokeji.cn/asset/cop-cli/install.ps1 | iex

之后升级只要一条命令：

cop-cli update

配上本地 AI 助手：两份技能

如果你本机已经在用 AI 编程助手（Claude Code、Cursor、Codex、Gemini 等），装完 cop-cli 后再执行一条命令：

cop-cli skill setup

它会在你的项目目录下装出两份技能，让你的 AI 助手立刻知道"曹操开放平台怎么对接、cop-cli 怎么用"。

两份技能

技能 它会做什么 什么时候找它
对接助手
cop-integration		 回答接口/签名/回调/错误码问题；帮你选定流程；按流程在你的工程里生成最小可用 SDK 正在写对接代码，或还在决定方案
联调助手
cop-order-testing		 陪你把联调场景一层层问清楚再切换；跑完整条订单闭环；造沙箱测试司机；报错时给出下一步 代码写完了，要实际跑单验证

举几个真实说法

对对接助手说：

  • 「我用 Java + Spring，帮我把最短的用车下单流程封一个 SDK 出来」
  • 「我们要同时对接多家运力，这个流程我该怎么设计？」
  • 「我的签名算出来和你的不一样，帮我对一下」

对联调助手说：

  • 「帮我把这个应用切成需要确认接单的场景」
  • 「跑一单，司机举手后帮我确认接单」
  • 「叫了单没人接，帮我查是哪里不对」

为什么值得装

  • 知识随时同步：对接助手用的是随时更新的官方知识库，不靠模型记忆编答案，回答会给出引用的文档。
  • 代码贴着你的工程：生成 SDK 不会硬塞你没用过的依赖，签名统一收口在一个类里，生成后还会先对拍签名、再对沙箱真调一次只读接口做验证。
  • 联调不靠猜：卡住时按固定检查清单逐项排除，而不是反复重试同一条命令。
  • 版本不会错配：技能内容随 cop-cli 一起分发，cop-cli update 会自动重装，两边永远同版本。

三步走通一单

下面这些命令你可以自己敲，也可以直接让装了技能的 AI 助手替你敲。

# 1. 登录（浏览器完成验证，凭据存在本机）
cop-cli auth login

# 2. 选定要联调的沙箱应用
cop-cli account app list
cop-cli account app use <client_id>

# 3. 存两个常用地点，然后叫一单
cop-cli place add 公司 --name 曹操总部 --address 杭州市滨江区 --lat 30.18 --lng 120.20 --city-code 0571
cop-cli place add 东站 --name 杭州东站 --address 天城路1号 --lat 30.29 --lng 120.21 --city-code 0571

cop-cli order create --from @公司 --to @东站 --yes

拿到订单号后：

cop-cli order detail --order-no <订单号>      # 看当前状态
cop-cli order cancel --order-no <订单号> --yes # 取消

切换联调场景

场景是一组预先配好的联调条件的组合——是否走预锁定（司机举手后再确认接单）、取消订单是否收取消费、开票方式、支付方式等。想验哪条流程，就把应用切到对应场景，不用逐项去改配置。

cop-cli app config show          # 先看当前应用的配置和所处场景
cop-cli app scenario list        # 列出可切换的场景
cop-cli app scenario use <场景名> --yes

scenario list 的每个场景都带 title、description 和 affects——affects 说明这次切换会连带影响什么，切换前务必先看它。场景清单由平台侧维护，会随能力增加而变化，所以不要把场景名写死进脚本，每次先 list。

切完再 app config show 确认已生效。不带 --yes 时只打印将要提交的变更预览、不真正切换（见下方「两道安全闸门」）。

⚠️ 预锁定相关的切换代价很高：它决定了回调里 event=1 是"订单已成立"还是"司机只是举手"——切换后你这边处理回调的逻辑要跟着改，双方都要重新联调。建议在对接初期就定下来，不要中途变更。这条流程本身见 确认接单，回调事件取值见 订单状态及类型。

用云端或本地 AI 助手时不用记命令，直接说「把这个应用切成需要确认接单的场景」，它会先把场景问清楚、给出影响面再切。

接口权限自己开

每篇接口文档的「沙箱API ID」就是给这里用的。想调某个接口却报未授权时：

cop-cli app api add --api-id <沙箱API ID> --yes

开通即时生效，网关配置最多 60 秒同步完成。

一单从头到尾长什么样

订单联调闭环

从"司机接单"到"待支付"之间的每一步——上线、出发接乘客、到达上车点、开始计费、结束计费、结算——现在都可以用 cop-cli driver 命令代替司机端 App 完成，不用再下载司机端 App，见下方「用命令行推进行程」。想看司机端真实界面的，仍可按 请求域名及测试司机端 下载 App 走一遍，两种方式效果一样。

用命令行推进行程

单子派到你的沙箱司机后，按下面顺序推进，每步后用 order detail 看 order_status 确认已到位：

cop-cli driver online --lat <纬度> --lng <经度>   # 司机上线，所有履约动作的前提
cop-cli order create --from @公司 --to @东站 --yes # 叫单
cop-cli driver grab   --order-no <订单号>          # 仅预约/接送机单：抢单 → 2 已派单
cop-cli driver depart --order-no <订单号>          # 仅预约/接送机单：出发接乘客 → 9
cop-cli driver arrive --order-no <订单号>          # 到达上车点 → 12
cop-cli driver start  --order-no <订单号>          # 开始计费 → 3
cop-cli driver stop   --order-no <订单号>          # 结束计费 → 8
cop-cli driver bill   --order-no <订单号>          # 查看账单
cop-cli driver settle --order-no <订单号> --park-fee 500  # 结算 → 5 待支付
  • 坐标不用手填：depart/arrive/start 默认取上车点，stop/settle 默认取目的地；传 --lat/--lng 可覆盖。
  • 司机编号：--driver-no 不传时取 driver create/driver show 记在本地的那个司机。
  • 附加费单位是分：settle 支持 --park-fee/--high-speed-fee/--bridge-fee/--other-fee，默认 0；--park-fee 500 即 5 元停车费。
  • 实时单靠强制接单派到司机（先 driver force-accept enable --yes）；预约/接送机单强接不生效，要用 driver grab 抢单，抢单结果是异步的，跑完用 order detail 看 order_status 是否变成 2。
  • 预锁定场景先确认接单再推进：实时单派到司机后先是「举手」（is_handup=true），此时直接 driver arrive 会报「网络繁忙，请重试」。要在 7 秒内 order confirm，订单成立后再推进。
  • 订单状态以 order detail 为准：driver detail 里的 orderStatus 是司机端视角，可能与业务订单状态不一致，不要用它判断进度。

用 AI 助手时直接说「把这单从到达上车点一路推到待支付」即可。

沙箱司机也能一条命令造出来

沙箱司机有三种创建方式，效果完全一样（同一套数据，造出来的司机都能登录司机端 App）：

方式 怎么做
命令行 cop-cli driver create --city-code 0571 --service-type 2 --yes
云端 / 本地 AI 助手 直接说「给我造一个杭州的沙箱司机」
网页 开发者管理中心 → 沙箱应用 → 调试 → 接单调试，见 请求域名及测试司机端

命令会返回司机手机号，用 driver online 上线后即可接单；想用司机端 App 的，用这个手机号登录（验证码任意 4 位数字）。查看当前应用下已有的沙箱司机：

cop-cli driver show

造司机时的城市和车型必须和叫单参数对齐，否则派不到单。不想让司机跑到起点附近，可以让他必接这个应用的单：

cop-cli driver force-accept enable --yes

注意它只免掉「位置」这一项——城市、车型、司机是否已上线（cop-cli driver online）仍要对齐。司机端 App 的下载与登录（可选）、以及完整的"无法接单自检清单"见 请求域名及测试司机端。

两道安全闸门

闸门 作用
--dry-run 只打印将要发出的请求，不真正调用。想先看看参数对不对时加上它
--yes 取消、改费、改配置这类操作不带 --yes 时只给预览，加上才真正执行

输出是 JSON，方便进脚本

成功走标准输出，失败走标准错误，格式固定，错误里带可执行的下一步提示。配合 --jq 可以直接取某个字段：

cop-cli order create --from @公司 --to @东站 --yes --jq .order_no