didi-ride-skill

DiDi配車サービス (DiDi Ride Skill)

DiDi MCP Server APIを通じて、配車、注文の照会、ドライバーの位置確認、配車予約、ルート検索、周辺検索の機能を提供します。

---

1. クイックスタート（2分）

1.1 MCP KEYを取得する

方法1：「滴滴出行App」でQRコードをスキャン（おすすめ、最速）

⚠️ エージェントへの注意：ユーザーのクライアントではMarkdown画像をレンダリングできないため、上記の画像構文をそのまま出力することは禁止です。ユーザーにQRコードを送信する場合は、### 3.9 MCP KEYと設定 の openclaw message send コマンドを実行して画像を送信してください。

滴滴出行 Appを開いてQRコードをスキャンすると、MCP Keyをすぐに取得できます。

方法2：公式サイトにアクセスする

https://mcp.didichuxing.com/claw にアクセスして、MCP Keyを取得してください。

1.2 Keyを設定する

方法1：会話で入力する（おすすめ）

会話でMCP Keyを直接伝えていただければ、設定をお手伝いします。

你: 我的 MCP Key 是 xxxxxx

方法2：OpenClaw設定ファイル

~/.openclaw/openclaw.json を編集して、以下を追加してください。

{
  "skills": {
    "entries": {
      "didi-ride-skill": {
        "enabled": true,
        "apiKey": "你的MCP_KEY"  // apiKey 是 OpenClaw 标准字段名，存储的值就是滴滴平台的 MCP KEY
      }
    }
  }
}

1.3 使用を開始する

設定が完了したら、そのまま会話を始められます。

你: 打车去北京西站
你: 帮我查一下从国贸到三里屯的路线
你: 查询订单

初回使用時に、OpenClawからmcporterツールのインストールを求められます。

---

2. ユーザーガイド

このSkillでは、以下の操作ができます。

• 配車：「[場所]まで配車して」「家に帰る」「職場に行く」と直接伝えます
• 料金確認：A地点からB地点までの料金を確認します
• 注文の照会：「注文を照会」と入力すると、現在の注文状況（ドライバーの位置、乗車の進捗など）を確認できます
• ドライバーの位置：ドライバーがどこにいるか、到着までどれくらいかを確認します
• 配車予約：「15分後に配車して」「明日の9時に空港へ」と伝えます
• ルート検索：車、バス、徒歩、自転車のルート
• 注文のキャンセル：現在の注文をキャンセルします

---

3. エージェント向け実行指示

以下はAIの実行時に参照する内容です。ユーザーは無視してかまいません。

3.1 ファイル一覧

必要に応じて以下のファイルを読み込み、未読の内容を推測しないでください。

ファイル	用途	読み込むタイミング
SKILL.md	トリガー、メインフロー、必須ゲート、注文照会のルール、配車予約のルール	トリガーのたびに必ず読む
references/workflow.md	各段階の詳細なフローとコマンドの形式	実装の詳細が必要なときに読む
references/api_references.md	MCP関数のシグネチャとパラメーター定義	ツールを呼び出す前に必ず確認する
references/error_handling.md	create_orderの失敗時の案内、mcporterでよくあるエラー、統一エラーコード、パラメーターエラーのトラブルシューティング、apiKeyプレースホルダーの漏えい	⚠️ 呼び出しに失敗した場合（HTTP error / StatusCode=400 / -32xxxエラーコード / Unknown MCP server / Missing KEY parameter / SSE error: Invalid content type）は必ずこのファイルを読む
references/setup.md	mcporterのインストールとMCP KEYの設定手順全般	ユーザーからインストールや設定について質問されたときに読む
assets/PREFERENCE.md	住所の別名、車種、電話番号の設定	ユーザーが住所の別名（自宅、会社、母親の家など）、車種、電話番号に言及した場合、または出発地と目的地を明示していない場合は必ず読む。別名の照合ルールについては実行前チェックの第7項を参照

3.2 実行前の確認

1. mcporter の確認：mcporter が存在しない場合（command not found）、処理を停止し、references/setup.md を読むようユーザーに案内します。mcporter がなければ MCP ツールを呼び出せず、以降の処理は一切実行できません。

2. Key の確認：openclaw config get skills.entries.didi-ride-skill.apiKey を実行し、出力が空、または __OPENCLAW_REDACTED__ 以外の場合は、### 3.9 MCP KEY 与配置 の手順に沿って案内します。Key がない場合、mcporter のエラーメッセージは誤解を招くため、回避を試みないでください。

   • ⚠️ Key が設定済み（__OPENCLAW_REDACTED__ が返される）なのに mcporter が Missing KEY parameter を返す場合：Key が無効になったわけではありません。ユーザーに Key を求めてはいけません。トラブルシューティングの手順は references/error_handling.md の「mcporter Missing KEY parameter」セクションを参照してください。
   • ⚠️ __OPENCLAW_REDACTED__ は「設定済み」を示す番兵値であり、実際の Key ではありません：openclaw config get（--raw を含む）から Key のリテラルを取得することは禁止です。URL 内の ?key=... には必ず $DIDI_MCP_KEY を使用してください。番兵値を誤って URL に連結すると SSE error: Invalid content type が発生します。詳しくは error_handling.md の同名セクションを参照してください。

3. mcporter.json の注意事項：この skill は URL 直接接続モードを使用し、config/mcporter.json に依存しません。このファイルの作成や変更は禁止です。mcporter の起動時に JSON 検証エラー（invalid_type / Failed to parse JSON）が発生した場合は、references/error_handling.md の「mcporter.json 検証エラー」セクションを参照してください。

4. mcporter の呼び出し形式（固定の記述です。変更しないでください）：

MCP_URL="https://mcp.didichuxing.com/mcp-servers?key=$DIDI_MCP_KEY"
mcporter call "$MCP_URL" <tool> --args '{"key":"value"}'

必ず読むべき注意事項：

• MCP_URL の代入と "$MCP_URL" の参照は、どちらも必ず半角の二重引用符で囲んでください。そうしないと $DIDI_MCP_KEY が shell で展開されません。単引用符や全角引用符は禁止です。
• --server フラグの追加は禁止です（例：--server didi-mcp）。--server を付けると mcporter は登録済みの名前付き server を検索します。見つからない場合は Unknown MCP server が直接返され、見つかった場合でも URL パラメーターと競合して Missing tool name が発生します。
• パラメーター名は references/api_references.md で確認してください。記憶に頼らないでください。よくある致命的な誤り：keyword → keywords；region → city；from_lng/from_lat/to_lng/to_lat → from_name/from_lat/from_lng/to_name/to_lat/to_lng（4 つではなく 6 つのフィールド）。
• パラメーターが誤っている場合、mcporter のエラーメッセージは backend call failed: ... StatusCode=400 です（具体的にどのパラメーターが誤っているかは表示されません）。このエラーが発生したら、まずパラメーター名を確認してください。詳しくは references/error_handling.md を参照してください。
• パラメーター名が不確かな場合は、mcporter list "$MCP_URL" を実行して、すべてのツールの完全なシグネチャを確認してください。

5. パラメーター値は必ず引用符で囲んでください（文字列形式）。緯度・経度や product_category などの数値的な意味を持つフィールドも対象です。API は文字列しか受け付けないため、そうしないと「必須パラメーターがありません」というエラーが発生します。

6. 先に見積もり、その後に注文：taxi_create_order は taxi_estimate が返す traceId に依存します。traceId がなければ注文は失敗します。traceId には有効期限があり、期限切れ（-32021 エラー）の場合は再度見積もりが必要です。

7. 出発地と目的地の処理：

   座標の取得元：座標は必ず maps_textsearch から取得してください。推測してはいけません。会話履歴の記憶で出発地や目的地を補ってはいけません。ユーザーはすでに別の場所に移動している可能性があります。

   不足情報の補完（優先順位順）：① assets/PREFERENCE.md を読み、住所の別名があり、値が空でない場合は、状況から推測します（朝→出発地は「家」、退勤後→出発地は「会社」。別名の行が存在しても住所が空なら未設定です）→ ② 使用できる別名がなければ、ユーザーに直接尋ねます。

   別名の照合：完全一致を優先します。「家」は「家」のみと照合し、「ママの家」とは照合しません。「ママ」の意味が明確に含まれている場合に限り、「ママの家」と照合します。読み取り時は表全体をスキャンしてください（次の ## まで）。先頭の 2 行だけを見てはいけません。ユーザーが「ママの家」「息子の学校」「ジム」などのカスタム別名を追加している可能性があります。

   確認ルール：推測した出発地・目的地、または maps_textsearch が複数の候補を返した場合は、メインフローの step 2 で必ずユーザーに確認します。ユーザーが明示的に指定し、完全一致した場所は確認不要です。

8. taxi_create_order のパラメーター制約：

• 受け付けるフィールドは 3 つのみです：estimate_trace_id、product_category、caller_car_phone（任意）
• taxi_create_order の caller_car_phone がユーザーから提供されていない場合は、assets/PREFERENCE.md の「デフォルト設定」表から読み取ります。どちらにもない場合は、このパラメーターを渡さないでください。会話中にユーザーへ電話番号を何度も求めることは禁止です。skill レベルでは電話番号なしでの注文がすでに許可されており、一度尋ねてもユーザーが応じなければ「デフォルトを使用する／渡さない」と見なします。
• taxi_estimate の座標・名称フィールド（from_lat / from_lng / from_name / to_lat / to_lng / to_name）を含めてはいけません。

3.3 ユーザー確認方針

場面	ルール
配車（即時／予約）	住所を推測した場合、または検索結果に複数の候補がある場合は、出発地と目的地を必ず確認します（メインフローの step 2 を参照）。ユーザーが明示的に指定し、完全一致する場合は確認不要です。確認後に見積もりと注文を行います
注文のキャンセル	ユーザーが「注文をキャンセルして」と言った場合でも、まず「キャンセルを確定しますか？」と明確に尋ね、ユーザーの確認を得てから taxi_cancel_order を呼び出す必要があります。ユーザーのキャンセル意思 ≠ キャンセルの確認。

3.4 主流程（最小可执行）

1. 地址解析：maps_textsearch（必要时结合 assets/PREFERENCE.md，按执行前检查第 7 条处理）。
2. 确认起终点：
   • 单一精确匹配（用户描述明确 + maps_textsearch 仅返回 1 个结果）→ 无需确认，直接使用；
   • 多个候选（maps_textsearch 返回 ≥2 个同名或近似地点）→ 必须列出至少前 3 个候选供用户选择（如"搜索到以下万达广场：1) 朝阳CBD店 2) 石景山店 3) 通州店，请问您要去哪个？"），不要自行代选或只展示一个；
   • 别名推断（从 PREFERENCE.md 推断的起终点）→ 向用户确认 + 告知推断来源（如"按偏好里「家」推断终点是望京 SOHO，对吗？"）；
   • 用户明确指定且文本精确匹配的地点 → 无需确认。用户纠正则按纠正内容重新解析。
3. 价格预估：taxi_estimate，记录 traceId。
4. 车型决策（优先级：当前消息 > 偏好 > 询问用户）：
   • 用户在当前消息中明确指定车型（如"叫快车""帮我叫专车"）→ 在 taxi_estimate 返回列表中精确匹配对应 productCategory（快车=1，专车=8），覆盖一切偏好设置；
   • 用户未指定 → 使用 assets/PREFERENCE.md 中场景车型偏好的精确 productCategory 值；
   • 偏好也未配置 → 向用户询问车型，不要自行推荐；
   • 注意：快车（1）和特惠快车（201）是不同服务等级，不可因价格更优而自动替换；
   • 可用车型以 taxi_estimate API 返回为准。若不包含指定/偏好的 productCategory，向用户说明并让其重新选择，不要默默用近似车型替代。
   • ⚡ 简化原则（尤其对 reasoning 模型）：用户在当前消息中说什么车型就用什么，不要进一步质疑或反复确认；偏好缺失时直接向用户问一次即可，不要在同一轮列出多个权衡选项让用户挑。规则很短，不要过度展开思考分支。
5. 创建订单：taxi_create_order（使用最新 traceId）。
   • 若此调用返回 Streamable HTTP error: Unexpected content type: text/plain，立即停止流程，按 references/error_handling.md 的「taxi_create_order 调用失败」章节向用户输出固定文案。禁止重试、禁止切换 Key、禁止跳过此步继续往下。
6. 结果输出：给出订单号、起终点、车型、预估价，末尾提示 💡 发送「查询订单」可了解当前订单状态，并告知 ⏱️ 将在 5 分钟后自动为您回查订单状态。
7. ⚠️ 自动回查（必做）：根据 ### 3.8 发单后自动回查 中的 cron 指令内容，创建定时任务，参数信息严格遵循章节内要求。此步不可省略。

3.5 偏好设置更新

当用户要求设置/记住/记一下/帮我记/保存地址别名、车型偏好或手机号时，必须通过文件编辑工具（Edit / Write）修改 assets/PREFERENCE.md 对应的 markdown 表格行。严禁仅以文字回复"记住了/已保存"而不调用文件编辑工具——偏好必须落盘到文件，口头承诺无效。

执行步骤：

1. Read 读取 assets/PREFERENCE.md 完整内容（注意表格可能已有用户追加的行）；
2. 定位要更新的表格行（地址别名表 / 场景车型偏好表 / 默认偏好表）；
3. 对地址别名：先调用 maps_textsearch 获取坐标，再更新表格行；
4. 调用 Edit（替换单行）或 Write（整表重写）写入新值；
5. 回读验证：再次 Read 确认新值已落盘。若未成功，告知用户并重试。

• 地址别名（"我家在…"、"公司在…"、"儿子的学校是…"、"妈妈家在…"）：先调用 maps_textsearch 解析地址获取坐标，然后更新「地址别名」表——已有别名更新对应行，新别名追加新行。别名由用户定义，不限于"家""公司"。
• 场景车型（"上班用快车"、"下班用特惠和快车"）：更新「场景车型偏好」表对应行。品类代码参考表底注释，多车型用英文逗号分隔（如 1,201）。
• 叫车手机号（"我的手机号是…"）：更新「默认偏好」表中的叫车手机号行。
• 创建订单时：若 PREFERENCE.md 中配置了叫车手机号，将其作为 caller_car_phone 参数传入 taxi_create_order，caller_car_phone 为可选参数，若未配置则不传。

3.6 查询订单

触发词：查询订单 / 查询订单 <orderId>

订单号来源（优先级从高到低）：

1. 用户消息中明确给出；
2. 当前对话上下文中最近一次创建的订单号；
3. 以上均无时，向用户询问。

调用命令：

MCP_URL="https://mcp.didichuxing.com/mcp-servers?key=$DIDI_MCP_KEY"
mcporter call "$MCP_URL" taxi_query_order --args '{"order_id":"ORDER_ID"}'

3.6.1 状态码与输出规则

code	含义	必须输出
0	匹配中	⏳ 正在为您匹配司机，请稍候
1	司机已接单	必须展示：司机姓名、车型、车牌、电话；距上车点距离和预计到达时间
2	司机已到达	🔔 司机已到达上车点，请前往上车
4	行程进行中	🚗 行程已开始
5	订单完成	✅ 行程结束，展示费用（如有）
6	订单已被系统取消	❌ 订单已被系统取消
7	订单已被取消	❌ 订单已取消
3/8-12	其他终态	显示对应状态描述

3.7 预约出行规则

当用户要求在特定时间叫车（如"15分钟后"、"明天9点"）：

• 使用 cron 一次性任务（--at），到点由 isolated agent 独立执行完整打车流程；
• ⚠️ --message 必须包含完整起终点（带城市前缀）和车型，isolated session 无历史上下文。起点或终点缺失时先从 assets/PREFERENCE.md 推断并向用户确认，推断不了则必须先询问用户，不要自行推断未知信息；
• 到点后 agent 自行执行：地址解析 → 价格预估（获取最新 traceId）→ 创建订单；
• 如果无法获取当前会话的 metadata（channel/chat_id），仅跳过 cron 创建步骤，其余流程（地址解析 → 价格预估 → 展示结果）正常执行不受影响。在回复中提醒用户到时手动发消息叫车。metadata 不可用 ≠ 放弃整个打车流程；
• 如果定时任务创建失败，必须在回复中提示用户，不能默默失败。

# ⚠️ 占位符替换规则：所有 <XXX> 形式都是占位符，必须替换为真实值；
#    禁止保留 <> 字面、禁止当成 shell 变量加 $（不是 $TIME / $CHAT_ID）。
#   <FROM_NAME>    → 带城市前缀的起点全称（如"北京市西二旗地铁站"）
#   <TO_NAME>      → 带城市前缀的终点全称（如"北京市佰嘉城小区"）
#   <VEHICLE>      → 车型（如"快车"）
#   <TIME>         → 见下方时间规则（如 "10m" / "2h" / ISO 时间）
#   <CHANNEL_NAME> → 当前会话 metadata 中的 channel 字段（如 feishu、telegram），命令行参数不带引号；不可用 last
#   <CHAT_ID>      → 当前会话 metadata 中的 chat_id 字段

openclaw cron add \
  --name "didi-ride-skill:$(date +%s)" \
  --at "<TIME>" \
  --session isolated \
  --message "执行定时打车：起点「<FROM_NAME>」，终点「<TO_NAME>」，车型「<VEHICLE>」。请完整执行打车流程：地址解析 → 价格预估（获取最新 traceId）→ 创建订单。订单创建成功后，输出订单信息并提示用户可发送「查询订单」了解订单状态，同时创建 5 分钟后自动回查 cron（模板见 SKILL.md 第 3.8 节「发单后自动回查」）。" \
  --announce \
  --channel <CHANNEL_NAME> \
  --to "<CHAT_ID>"

3.7.1 TIME 填写规则

场景	写法	示例
相对时间（X 分钟/小时后）	duration 格式	15m / 2h / 1h30m
绝对时间（具体时刻）	本地时区 ISO 格式	$(date -d '明天 09:00' '+%Y-%m-%dT%H:%M:%S+08:00')

• 相对时间（如 15m）无需格式化，直接使用
• 绝对时间使用带时区的 ISO 8601 格式：YYYY-MM-DDTHH:MM:SS+08:00（北京时间东八区）

系统兼容性说明：

• Linux (GNU date): date -d '明天 09:00' '+%Y-%m-%dT%H:%M:%S+08:00'
• macOS (BSD date): TZ=Asia/Shanghai date -j -v+1d -f '%H:%M' '09:00' '+%Y-%m-%dT%H:%M:%S+08:00'

3.8 发单后自动回查

发单成功后（实时单或预约单），根据本章节下文 "openclaw cron add" 命令，创建 cron 任务，务必按照本章节下文bash命令参数设置。

• 如果无法获取当前会话的 metadata（channel/chat_id），仅跳过 cron 创建步骤，主流程正常完成（已出单则告知用户"5 分钟后可发送'查询订单'了解最新状态"）。
• 如果定时任务创建失败（命令本身报错），必须在回复中提示用户，不能默默失败。

# ⚠️ 占位符替换规则：所有 <XXX> 形式都是占位符，必须替换为真实值，禁止保留 <> 字面或加 $ 当 shell 变量。
#   <ORDER_ID>     → 实际订单号（taxi_create_order 返回）
#   <CHANNEL_NAME> / <CHAT_ID> → 同 §3.7，从会话 metadata 读取或用兜底值

openclaw cron add \
  --name "didi-ride-skill:check:<ORDER_ID>" \
  --at "5m" \
  --session isolated \
  --message "查询滴滴订单状态：订单号 <ORDER_ID>。调用 taxi_query_order 查询并输出当前状态。如果司机已接单，输出司机姓名、车型、车牌、电话及预计到达时间；如果仍在匹配中，提示用户耐心等待。" \
  --announce \
  --channel <CHANNEL_NAME> \
  --to "<CHAT_ID>"

3.9 MCP KEY 与配置

术语说明：滴滴平台称此凭证为「MCP KEY」，OpenClaw 配置字段统一叫 apiKey，注入后的环境变量为 DIDI_MCP_KEY——三者是同一个值。通过 openclaw config set 持久化后，OpenClaw 在每次 agent run 启动时自动注入为环境变量。

3.9.1 检查 Key 状态

# 仅用于判断 DIDI_MCP_KEY 是否已配置；输出不是 Key 值，不可代入 URL
openclaw config get skills.entries.didi-ride-skill.apiKey

结果输出为空 = 未配置；输出 __OPENCLAW_REDACTED__ = 已配置，必须用环境变量 $DIDI_MCP_KEY 拼接 URL。

⚠️ openclaw config get（含 --raw）永远不返回真实 Key——任何把哨兵值拼入 URL/header/参数的请求都会失败，见 error_handling.md「SSE error / apiKey 占位符泄漏」。

3.9.2 持久化用户 Key

⚠️ 当用户回复了 Key（如"我的 Key 是 xxxxxx"），必须执行以下命令持久化 & 在当前 Shell 生效：

#   YOUR_KEY → 实际的 MCP KEY
openclaw config set 'skills.entries.didi-ride-skill.apiKey' 'YOUR_KEY'
export DIDI_MCP_KEY='YOUR_KEY'

• 持久化后 OpenClaw 在所有后续 agent run（含 cron isolated session）中自动注入 DIDI_MCP_KEY
• ⚠️⚠️⚠️ 命令输出 "Restart the gateway to apply." ——这是通用提示，必须忽略，禁止执行 restart。apiKey 每次 agent run 动态读取，无需重启；强制重启会导致网关崩溃

3.9.3 Key 缺失或鉴权失败

⚠️ Key 未配置或 MCP 返回鉴权失败（error.code: -32002）时，依次执行：

1. 发送二维码图片（{CHAT_ID} → metadata 的 chat_id，{CHANNEL_NAME} → metadata 的 channel）：

openclaw message send --channel {CHANNEL_NAME} --target {CHAT_ID} --media "https://s3-yspu-cdn.didistatic.com/mcp-web/qrcode/didi_ride_skill_qrcode.png" --message "滴滴出行APP扫码获取MCP Key，解锁一键打车"

2. 输出文字：

您还没有配置 DIDI_MCP_KEY 或 Key 已失效，请访问 滴滴MCP平台 获取 MCP KEY，然后配置环境变量或在 OpenClaw 配置文件中设置。

3.10 工具清单

领域	工具
地图	maps_textsearch, maps_regeocode
路线	maps_direction_driving, maps_direction_transit, maps_direction_walking, maps_direction_bicycling
周边	maps_place_around
打车	taxi_estimate（预估）, taxi_create_order（下单）, taxi_query_order（查单+司机位置）, taxi_cancel_order（取消）