SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsdidi-ride-skill

didi-ride-skill

General & other

View repository

Updated 10-15 17:26

About this skill

DiDi Ride-Hailing Service (DiDi Ride Skill)

Provides ride-hailing, order querying, driver location, scheduled ride booking, route planning, and nearby search capabilities through the DiDi MCP Server API.

1. Quick Start (2 minutes)

1.1 Get MCP KEY

Method 1: Scan the QR code with the "DiDi Ride-Hailing App" (recommended, fastest)

Scan the QR code with the DiDi Ride-Hailing APP to get the MCP Key and unlock one-tap ride-hailing

⚠️ Agent note: The user's client cannot render Markdown images,do not directly output the image syntax above. When you need to send a QR code to the user, execute the ### 3.9 MCP KEY 与配置 in openclaw message send command to send the image.

Open the DiDi Ride-Hailing App, scan the QR code, and you can quickly get the MCP Key.

Method 2: Visit the official website

Visit https://mcp.didichuxing.com/claw to get your MCP Key.

1.2 Configure Key

Method 1: Enter in the conversation (recommended)

Tell me your MCP Key directly in the conversation, and I will configure it for you:

你: 我的 MCP Key 是 xxxxxx

Method 2: OpenClaw configuration file

Edit ~/.openclaw/openclaw.json, add:

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

1.3 Start Using

After configuration is complete, just talk directly:

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

On first use, OpenClaw will prompt you to install the mcporter tool.

2. User Guide

This Skill supports the following operations:

  • Ride-hailing: Just say "ride-hailing to [location]", "go home", "go to work"
  • Check price: Check how much it costs from A to B
  • Query order: Enter "query order" to learn the current order status (driver location, trip progress, etc.)
  • Driver location: Where is the driver, how long until arrival
  • Scheduled ride: "Hail a ride in 15 minutes", "go to the airport at 9 tomorrow"
  • Route planning: Driving/transit/walking/cycling routes
  • Cancel order: Cancel the current order

3. Agent Execution Instructions

The following content is for AI execution reference; users may ignore it.

3.1 File Map

Read the following files as needed; do not guess at content you have not read:

File Purpose When to Read
SKILL.md Triggers, main flow, hard gates, order query rules, scheduled ride rules Must read on every trigger
references/workflow.md Phased detailed flow and command patterns Read when implementation details are needed
references/api_references.md MCP function signatures and parameter definitions Before every tool callmustverify
references/error_handling.md Common errors and recovery strategies ⚠️ When encountering a call failure (such as a 400 error), you must read this file
references/setup.md Complete steps for installing mcporter and configuring the MCP KEY Read when the user asks about installation/configuration
assets/PREFERENCE.md Address aliases/vehicle model/phone number preferences When the user mentions an alias address (home, company, mom's house, etc.), vehicle model, or phone number, or does not explicitly provide the origin and destinationMustread. See item 6 of the pre-execution checks for alias matching rules

3.2 Pre-execution checks

  1. Check mcporter: if mcporter does not exist (command not found), stop and guide the user to read references/setup.md. Without mcporter, no MCP tool can be called, and no subsequent process can be executed.

  2. Check the Key: run openclaw config get skills.entries.didi-ride-skill.apiKey, if the output is empty or not __OPENCLAW_REDACTED__, follow the ### 3.9 MCP KEY 与配置 process for guidance. When the Key is missing, mcporter's error messages are misleading; do not try to bypass this.

    • ⚠️ If the Key is already configured (returns __OPENCLAW_REDACTED__) but mcporter still reports Missing KEY parameter：this is not Key invalidation，it is forbidden to ask the user for the Key. For troubleshooting steps, see references/error_handling.md the "mcporter Missing KEY parameter" section in

  3. mcporter call format：

MCP_URL="https://mcp.didichuxing.com/mcp-servers?key=$DIDI_MCP_KEY"
mcporter call "$MCP_URL" <tool> --args '{"key":"value"}'
  1. Parameter values must be quoted(string format), otherwise the API will report "missing required parameter".
  2. Estimate first, then order：taxi_create_order depends on the taxi_estimate returned by traceId; without a traceId, the order will fail. The traceId is time-sensitive; once expired (-32021 error), you need to estimate again.
  3. Origin and destination handling：
    • Coordinates must come from maps_textsearch; do not guess coordinates out of thin air.
    • It is forbidden to fill in the origin and destination from conversation history memory—the user may have already changed locations.
    • When the origin or destination is missingcomplete it in the following order:
      • ① Read assets/PREFERENCE.md; if there is an address aliasand the address value is not empty, infer based on the scenario (e.g., morning→origin "home", after work→origin "company"). An alias line that exists but has an empty address = not configured.
      • ② If there is no usable alias, ask the user directly.
    • Alias matching rules (exact match first): "home" only matches the alias "home", not "mom's house"; it matches "mom's house" only when the semantics explicitly include "mom". The same applies to other custom aliases.
    • For inferred origins and destinations, or when maps_textsearch returns multiple candidate results, you must confirm with the user in step 2 of the main process; locations that the user explicitly specifies and that match exactly do not need confirmation.

3.3 User confirmation policy

Scenario Rule
Ride-hailing (real-time/scheduled) When the address is inferred or the search returns multiple candidates, the origin and destination must be confirmed (see step 2 of the main process); when the user explicitly specifies and it matches exactly, no confirmation is needed; after confirmation, estimate and place the order
Cancel order Even if the user says "cancel the order", you must still first explicitly ask "Confirm cancellation?", and only after the user replies to confirm may you call taxi_cancel_order. The user's intent to cancel ≠ cancellation confirmation.

3.4 Main Flow (Minimum Executable)

  1. Address parsing:maps_textsearch(if necessary, combine with assets/PREFERENCE.md, handle according to item 6 of the pre-execution check).
  2. Confirm origin and destination: inferred addresses (such as alias inference) or when maps_textsearch returns multiple candidate results, you must confirm with the user (e.g., "Departing from home to Capital Airport Terminal 3, confirm?"); locations explicitly specified by the user with an exact match do not need confirmation. If the user corrects it, re-parse according to the correction.
  3. Price estimate:taxi_estimate, record traceId。
  4. Vehicle type decision:
    • User explicitly specifies a vehicle type: use it directly;
    • User does not specify: use the scenario vehicle type preference or default vehicle type in assets/PREFERENCE.md ;
    • If no preference is configured either: ask the user for the vehicle type, do not recommend one yourself.
    • Available vehicle types are subject to what the taxi_estimate API returns; obtain the corresponding productCategory to create the order.
  5. Create order:taxi_create_order(use the latest traceId）。
  6. Result output: provide the order number, origin and destination, vehicle type, and estimated price, and at the end prompt 💡 发送「查询订单」可了解当前订单状态, and inform ⏱️ 将在 5 分钟后自动为您回查订单状态。
  7. ⚠️ Automatic follow-up check (mandatory): based on the cron instruction content in ### 3.8 发单后自动回查 , create a scheduled task; the parameter information must strictly follow the requirements in the section. This step cannot be omitted.

3.5 Preference Settings Update

When the user asks to set/remember/note down/help me remember/save an address alias, vehicle type preference, or phone number,you mustdirectly edit the markdown table row corresponding to assets/PREFERENCE.md .

  • Address alias("My home is at...", "The company is at...", "My son's school is...", "My mom's home is at..."): first call maps_textsearch to parse the address and obtain the coordinates, then update the "Address Alias" table—update the corresponding row for an existing alias, and append a new row for a new alias. Aliases are defined by the user and are not limited to "home" and "company".
  • Scenario vehicle type("Use Express for commuting to work", "Use Discount and Express for commuting home"): update the corresponding row in the "Scenario Vehicle Type Preference" table. For category codes, refer to the notes at the bottom of the table; separate multiple vehicle types with English commas (e.g., 1,201）。
  • Ride-hailing phone number("My phone number is..."): update the ride-hailing phone number row in the "Default Preferences" table.
  • When creating an order: if a ride-hailing phone number is configured in PREFERENCE.md, pass it as the caller_car_phone parameter to taxi_create_order。

3.6 Query Order

Trigger words:查询订单 / 查询订单 <orderId>

Order number sources (priority from high to low):

  1. Explicitly provided in the user's message;
  2. The most recently created order number in the current conversation context;
  3. If none of the above, ask the user.

Call command:

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 Status Codes and Output Rules

code Meaning Must output
0 Matching ⏳ Matching a driver for you, please wait
1 Driver has accepted the order Must display: driver name, vehicle type, license plate, phone number; distance to the pickup point and estimated arrival time
2 Driver has arrived 🔔 The driver has arrived at the pickup point, please proceed to the pickup
4 Trip in progress 🚗 The trip has started
5 Order completed ✅ Trip ended, display fare (if any)
6 Order has been canceled by the system ❌ Order has been canceled by the system
7 Order has been canceled ❌ Order canceled
3/8-12 Other final states Display the corresponding status description

3.7 Scheduled ride rules

When the user requests a ride at a specific time (such as "in 15 minutes", "tomorrow at 9 o'clock"):

  • Use a cron one-time task (--at), and when the time comes an isolated agent independently executes the complete ride-hailing process;
  • ⚠️ --message must include the complete origin and destination (with city prefix) and vehicle type; the isolated session has no historical context. If the origin or destination is missing, first infer from assets/PREFERENCE.md and confirm with the user; if it cannot be inferred, you must first ask the user,do not infer unknown information on your own；
  • When the time comes, the agent executes on its own: address resolution → price estimate (obtain the latest traceId) → create order;
  • If the metadata of the current session cannot be obtained, do not create a cron; instead, remind the user in the reply to check proactively;
  • If the scheduled task creation fails, you must notify the user in the reply; do not fail silently.
# ⚠️ 替换占位符：
#   FROM_NAME    → 带城市前缀的起点全称（如"北京市西二旗地铁站"）
#   TO_NAME      → 带城市前缀的终点全称（如"北京市佰嘉城小区"）
#   VEHICLE      → 车型（如"快车"）
#   TIME         → 见下方时间规则
#   CHANNEL_NAME → 当前会话 metadata 中的 channel 字段（如 feishu、telegram），CHANNEL_NAME 不需要带引号，例如: feishu ✅, "feishu" ❌。不允许使用 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 filling rules

Scenario Format Example
Relative time (in X minutes/hours) duration format 15m / 2h / 1h30m
Absolute time (specific time) Local timezone ISO format $(date -d '明天 09:00' '+%Y-%m-%dT%H:%M:%S+08:00')
  • Relative time (such as 15m) requires no formatting, use directly
  • Absolute time uses ISO 8601 format with timezone:YYYY-MM-DDTHH:MM:SS+08:00(Beijing Time, UTC+8)

System compatibility note:

  • 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 Automatic follow-up query after dispatch

After the order is dispatched successfully (real-time order or scheduled order), according to the "openclaw cron add" command later in this section, create a cron task, and be sure to set it according to the bash command parameters later in this section.

  • If the metadata of the current session cannot be obtained, do not create a cron; instead, remind the user in the reply to check the order status proactively.
  • If the scheduled task creation fails, you must notify the user in the reply; do not fail silently.
# ⚠️ 替换占位符：
#   ORDER_ID     → 实际订单号（taxi_create_order 返回）
#   CHANNEL_NAME → 当前会话 metadata 中的 channel 字段（如 feishu、telegram），CHANNEL_NAME 不需要带引号，例如: feishu ✅, "feishu" ❌。不允许使用 last 作为参数值。
#   CHAT_ID      → 当前会话 metadata 中的 chat_id 字段

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 and configuration

Terminology note: The DiDi platform calls this credential "MCP KEY", the OpenClaw configuration field is uniformly called apiKey, and the injected environment variable is DIDI_MCP_KEY—the three are the same value.

⚠️ Key source: after being persisted through openclaw config set , OpenClaw automatically injects it as the environment variable DIDI_MCP_KEY。

# ⚠️ 可以通过以下命令判断当前 DIDI_MCP_KEY 是否配置。如果输出 __OPENCLAW_REDACTED__ ，即为已配置，可在后面使用环境变量`DIDI_MCP_KEY`。
openclaw config get skills.entries.didi-ride-skill.apiKey

3.9.1 When the user provides the Key in the conversation (must be persisted)

When the user replies with the Key (such as "my Key is xxxxxx"),mustexecute the following command to persist it,strictly forbidden to only export to the current shell：

# ⚠️ 将 YOUR_KEY 替换为用户提供的实际值
openclaw config set 'skills.entries.didi-ride-skill.apiKey' 'YOUR_KEY'

After successful persistence:

  • OpenClaw automatically injects DIDI_MCP_KEY
  • ⚠️ After the command executes successfully, output "Restart the gateway to apply." ——This is a generic prompt, must be ignored, and any restart / reboot operation is forbidden。apiKey is dynamically read at the start of each agent run, and takes effect without restart; a forced restart will cause the gateway to crash.

⚠️ Key not configuredor When MCP returns an authentication failure (error.code: -32002), perform the following two steps:

  1. Execute the following "openclaw message send" command to send the QR code image ({CHAT_ID} → metadata's chat_id,{CHANNEL_NAME} → metadata's 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，解锁一键打车"
  1. Output text:

You have not configured DIDI_MCP_KEY or the Key is no longer valid. Please visit Didi MCP Platform to obtain an MCP KEY, then configure the environment variable or set it in the OpenClaw configuration file.

3.10 Tool List

Domain Tool
Ride-hailing maps_textsearch, taxi_estimate, taxi_create_order, taxi_query_order, taxi_get_driver_location, taxi_cancel_order, maps_regeocode, taxi_generate_ride_app_link(Alternative when the user does not have direct API ride-request permission: generate a deep link so the user can complete the ride request in the App)
Route maps_direction_driving, maps_direction_transit, maps_direction_walking, maps_direction_bicycling
Nearby maps_place_around