navclaw

# NavClaw 🦀 - 出行智能导航AI助手 / Smart Driving Navigator

## 概述 / Overview

**智能避堵导航 — 极限搜索数十条路线，可能比官方导航更优。一键跳转手机导航APP（iOS/Android）。**

**Smart congestion-avoidance navigator — exhaustive search of dozens of routes, may outperform default navigation. One-tap deep link to mobile nav apps.**

五阶段流水线规划（广撒网 → 精筛选 → 深加工 → 迭代优化 → 路线固化），导航 APP 通常只返回 2-3 条路线，NavClaw 短时间内探索数十种绕行组合。

5-phase pipeline (Wide Search → Fine Filter → Deep Processing → Iterative Optimization → Route Finalization). While navigation apps typically return 2-3 routes, NavClaw explores dozens of bypass combinations in seconds.

导航平台：目前支持高德，后续扩展更多平台。

Navigation platform: currently supports Amap (高德), more platforms coming soon.

---

**⚠️ 前置条件 / Prerequisites**：需要高德 Web 服务 API Key（免费申请）。获取优先级：

1. 从记忆中查找用户是否已提供过高德 API Key
2. 如果没有，询问用户是否有高德 API Key
3. 如果用户没有，引导获取：[高德开放平台](https://lbs.amap.com/) → 控制台 → 创建应用 → 添加 Key（Web 服务）

拿到 Key 后填入 `config.py` 的 `API_KEY` 字段：

```python
API_KEY = "你的高德API Key"
```

---

**触发方式 / Trigger**：

用户说"从 [起点] 到 [终点] 导航"、"导航从 [起点] 到 [终点]"或"navigate from [A] to [B]"即可自动执行。说"到家"时自动替换为 `config.py` 中的 `DEFAULT_DEST`。

Trigger when user says "navigate from [A] to [B]", "从 [起点] 到 [终点] 导航", or "drive to [destination]". Saying "到家" (go home) auto-substitutes `DEFAULT_DEST` from `config.py`.

---

**工作流程 / Workflow**：

调用 `wrapper.py --origin "起点" --dest "终点"`，经过五阶段规划（广撒网 → 精筛选 → 深加工 → 迭代优化 → 路线固化），生成大量路线方案（含绕行优化），自动发送 3 条消息到聊天平台 + 日志附件：

- 消息 1 — 完整对比表格
- 消息 2 — 快速导航链接
- 消息 3 — 最终推荐 + iOS/Android 一键深度链接

---

**输出格式 / Output**：

- **Mattermost（原生支持，推荐优先使用）**：

  需要先在 `config.py` 中配置 `MM_BASEURL...

# NavClaw 🦀    个人出行导航AI助手

[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
[![Python 3.8+](https://img.shields.io/badge/Python-3.8+-green.svg)](https://www.python.org/)
[![ClawHub](https://img.shields.io/badge/ClawHub-navclaw-orange)](https://clawhub.ai/AI4MSE/navclaw)

**智能导航路线规划** — 支持 OpenClaw 集成，也可独立使用。避堵规划 · 极限搜索优化方案 · 兼容 iOS 和 Android · 链接一键跳转手机导航 APP。附加工具箱：天气查询、周边地点搜索、地理编码、行政区划查询等。目前支持高德，后续扩展。(注意：附加工具箱需要更新版的SKILL.md，查看github对应项目）

**Intelligent route planner** — standalone or powered by OpenClaw. Congestion avoidance, exhaustive route optimization, iOS & Android deep links that open your navigation app in one tap.Bonus toolbox like  weather, POI search, geocoding, district query, etc. Currently supports Amap, more platforms coming

首版支持高德，后续扩展 / First supported platform: **Amap 高德** · 你可以贡献来使它更多平台支持 / More coming soon & Wecome your contribution.

 [📖 English](README_EN.md) · [GitHub](https://github.com/AI4MSE/NavClaw) · [技术文档](docs/technical_CN.md) · [Technical Doc (EN)](docs/technical_EN.md)

## 效果演示 / Demos
> Smart Navigation: 智能导航 极限搜索 智能绕行 一键跳转

![智能导航 极限搜索 智能绕行 一键跳转](img/Overview_Smart_Navi_Demo.png)

> Food & Weather & More... 餐饮，天气，以及其他无限可能

![餐饮x天气](img/Overview_Food_Weather_Demo.png)


## 核心特性 / Highlights

- 🔍 **极限搜索** — 多策略并发查询，可以短时间拿到**比如-高德官方-所有不同策略和推荐进行对比**，并生成数十种绕行组合， / Exhaustive search with dozens of bypass combinations
- 🚧 **智能避堵** — 基于 TMC 数据识别拥堵段，自动生成绕行方案，一定概率可**比官方推荐的更省时** （参考下面实际案例） / Smart congestion detection & auto-detour
- 📱 **一键导航** — iOS / Android 深度链接，点击直接跳转导航 APP / One-tap deep links for iOS & Android
- 🤖 **OpenClaw 原生** — AI Agent 技能，说"从北京到广州导航"即可 / Say *"navi...