折腾日志:把高德地图和特斯拉接入 Hermes

技术专业 · 21 天前

背景

因为爱人在外地工作,每个周末都是特斯拉的两地通勤,对于是否平安到达的判断就是不时的拿出手机打开特斯拉的app查看车辆的位置。在全面ai、agent的情况下,肯定是可以让ai把这个事情搞定的,帮我盯好行程位置。
现在在 Telegram 里问一句「车停在哪,开到临沂要多久」,它会先查车,再交给高德算路线。「如果进入某某区域,就及时发信息给我」Hermes就替我把整个过程守护了起来。

我的助手是 Hermes Agent,部署在群晖 NAS 的 Docker 里,通过 Telegram 和我对话,模型请求统一走 LiteLLM。Hermes 内置 MCP(Model Context Protocol)客户端,外部能力以 MCP Server 的形式接进来,工具会自动注册成 mcp_<服务名>_<工具名>。

这篇记录两件事:高德地图 MCP 的接入(十分钟搞定),以及特斯拉的接入(主线,涉及开发者注册、OAuth、自写 MCP 和几处踩坑)。文中所有密钥、车辆标识、域名和路径都做了替换。

一、高德地图 MCP 接入

高德官方提供远程 MCP 服务,走 Streamable HTTP,Hermes 里只需要加一个 url,不用装任何东西。

1. 申请 Key

在高德开放平台控制台创建应用、添加 Key,服务平台必须选「Web 服务」。选成 Web 端(JS)或移动端的 Key,调用时会报 USERKEY_PLAT_NOMATCH。个人开发者的免费额度,查吃饭的地方足够。

2. 写进 Hermes 配置

Hermes 的 MCP 配置在 config.yaml 的 mcp_servers 下:

mcp_servers:
  amap:
    url: "https://mcp.amap.com/mcp?key=<你的高德Key>"
    timeout: 60

改完在 Hermes 里执行 /reload-mcp,看到 mcp_amap_maps_around_search 这类工具就是接好了。可用的工具包括地址与坐标互转、天气、驾车/步行/骑行/公交路线、距离测量、关键词搜索、周边搜索和 POI 详情。

3. 使用要点

  • Hermes 在 NAS 上,不知道你人在哪。提问要带位置,比如「我在泉城广场附近,找 1 公里内人均 100 以内的鲁菜馆」。
  • 地名容易重名,带上城市或路名更准。
  • Key 是明文写在 URL 里的,配置文件不要进公开的 Git 仓库。

二、特斯拉接入:设计与安全原则

路线是:特斯拉官方 Fleet API → 自写的只读 MCP Server → Hermes。动手之前,我先把安全边界定死,因为这件事的风险不在车本身,而在权限泄露和 AI 误操作。

高德走远程 HTTP,特斯拉走容器内的 stdio 子进程;token 文件只在 NAS 上,公钥站点只给特斯拉校验域名用。

Fleet API 没有转向、刹车、加速这类接口,影响不了行驶。真正要防的是三件事:

  • token 泄露等于位置泄露:拿到 token 就能知道车在哪、人在哪、几点到家。如果还授了控车权限,对方能远程解锁。
  • AI 误操作或被注入:模型可能把「车锁了吗」理解成「开锁」;读网页、邮件时也可能被藏在里面的指令带偏。
  • 频繁唤醒:每次查位置都要车醒着,被轮询的话车无法休眠,停放掉电明显,API 也按次计费。

据此定下四条原则:

  1. 只授读权限:授权范围只要车辆信息和车辆位置,不要车辆命令;车上也不配对虚拟钥匙。即使 token 被盗,也控制不了车。
  2. 代码里不存在控车接口:MCP 只实现查询,不写解锁、空调、充电这些函数,从根上杜绝误操作。
  3. 唤醒在代码层面限制:默认完全禁止唤醒;需要时才打开,且两次唤醒至少间隔 30 分钟。不靠模型自觉。
  4. 自己部署,不用公共服务:MCP 跑在自己的 NAS 上,token 文件权限 600,不进 Git、不备份到云盘。

照这样配置,最坏的情况也只是「别人知道车在哪」,碰不到车本身。

三、开发者注册

国内车主走中国区:车是国内买的、账号在 tesla.cn,就必须在 developer.tesla.cn 单独建应用,需要 +86 手机号。中国区的认证服务器是 auth.tesla.cn,API 地址是 fleet-api.prd.cn.vn.cloud.tesla.cn,都和海外分开。

1. 客户端详细信息

字段填法
OAuth 授权类型授权码和机器对机器(个人用户选这个)
允许的源 URLhttps://car.example.com,只写到域名
允许的重定向 URIhttp://localhost:3000/callback,http 只允许本地主机
允许的返回 URL留空

重定向用本地地址的好处是:授权在自己电脑的浏览器里完成,回调地址不用暴露到公网。

2. 先把域名搭起来再填

第一次填源 URL 时报了「域无效」。原因是特斯拉会实时检查这个域名:要能解析、https 能打开、证书有效、域名里不能带 tesla 字样,也不能挂在反向代理(比如 Cloudflare 的橙色云朵)后面。

我在一台海外 VPS 上用 Caddy 起了个静态站,自动申请证书。顺手生成命令签名用的 P-256 密钥对,公钥放到特斯拉要求的固定路径:

mkdir -p /srv/car/.well-known/appspecific
openssl ecparam -name prime256v1 -genkey -noout -out ~/tesla-private-key.pem
openssl ec -in ~/tesla-private-key.pem -pubout \
  -out /srv/car/.well-known/appspecific/com.tesla.3p.public-key.pem
chmod 600 ~/tesla-private-key.pem

docker run -d --name car-web --restart unless-stopped \
  -p 80:80 -p 443:443 -v /srv/car:/srv -v caddy_data:/data \
  caddy caddy file-server --root /srv --domain car.example.com

公钥地址公开在互联网上没有问题,它本来就是给特斯拉验证用的。要保护的是私钥:它只放在 ~/,绝不能进网站目录。目录列表也不要打开。

3. API 和范围

只勾两项:车辆信息和车辆位置。个人资料、车辆命令、充电管理、能源产品一律不勾。范围以后可以在后台修改。

四、合作伙伴注册与 OAuth 授权

现成的 Tesla MCP 基本都写死了国际区的认证地址,直接用会失败。所以我先用 curl 把中国区流程走通,确认能拿到车辆数据,再写 MCP。

0. 变量

export CLIENT_ID="<开发者后台的 Client ID>"
export CLIENT_SECRET="<开发者后台的 Client Secret>"
export AUDIENCE="https://fleet-api.prd.cn.vn.cloud.tesla.cn"
export REDIRECT_URI="http://localhost:3000/callback"   # 与后台完全一致

1. 合作伙伴 token + 注册域名(一次性)

PARTNER_TOKEN=$(curl -s -X POST https://auth.tesla.cn/oauth2/v3/token \
  --data-urlencode grant_type=client_credentials \
  --data-urlencode client_id="$CLIENT_ID" \
  --data-urlencode client_secret="$CLIENT_SECRET" \
  --data-urlencode scope="openid vehicle_device_data vehicle_location" \
  --data-urlencode audience="$AUDIENCE" | jq -r .access_token)

curl -s -X POST "$AUDIENCE/api/1/partner_accounts" \
  -H "Authorization: Bearer $PARTNER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"domain":"car.example.com"}'

2. 车主授权

浏览器打开下面的地址,登录并同意:

https://auth.tesla.cn/oauth2/v3/authorize?response_type=code&client_id=<Client ID>&redirect_uri=http://localhost:3000/callback&scope=openid%20offline_access%20vehicle_device_data%20vehicle_location&state=<随机串>

授权后跳到 localhost,页面打不开是正常的。从地址栏复制 code= 后面的值,几分钟内换成 token:

curl -s -X POST https://auth.tesla.cn/oauth2/v3/token \
  --data-urlencode grant_type=authorization_code \
  --data-urlencode client_id="$CLIENT_ID" \
  --data-urlencode client_secret="$CLIENT_SECRET" \
  --data-urlencode code="$CODE" \
  --data-urlencode redirect_uri="$REDIRECT_URI" \
  --data-urlencode audience="$AUDIENCE" > tesla-token.json
chmod 600 tesla-token.json

tesla-token.json 里只有 token(access\_token 约 8 小时有效,外加 refresh\_token),没有车辆信息,这一点我一开始也搞混了。

3. 验证

ACCESS=$(jq -r .access_token tesla-token.json)
curl -s -H "Authorization: Bearer $ACCESS" "$AUDIENCE/api/1/vehicles" | jq

返回里能看到车辆、access_type: OWNER 和 state: online/asleep,中国区流程就通了。趁车醒着,再用 vehicle_data?endpoints=location_data 确认能拿到坐标。

五、自写只读 MCP:tesla\_cn\_mcp.py

与其改别人的代码,不如写一个专门对接中国区的精简版:单个 Python 文件,基于官方 mcp SDK 的 FastMCP(同时兼容 SDK 1.x 和 2.x,2.x 里它改名叫 MCPServer),依赖只有 mcp 和 httpx。

四个工具,全部只读

工具作用会不会唤醒车
list_vehicles列出车辆和在线状态,VIN 自动打码不会
vehicle_state查车是否醒着(online / asleep / offline)不会
vehicle_location高德坐标、高德地图链接、定位时间和距今分钟数默认不会
vehicle_summary电量、续航(公里)、充电、锁车、门窗、哨兵、温度、里程默认不会

token 自动刷新

access\_token 快过期时,脚本用 refresh\_token 换新的。特斯拉每次刷新都会轮换 refresh\_token,旧的立即作废,所以新 token 必须原子写回文件(先写临时文件再 os.replace,权限 600)。遇到 401 会强制刷新重试一次。

坐标转换

国内地图用 GCJ-02,GPS 是 WGS-84,直接放进高德会偏几百米。我不确定中国区 API 返回的是哪种,所以没有猜:自检模式会同时输出「转换后」和「原样」两个高德链接,打开看哪个和特斯拉 App 里的位置重合。实测是转换后的准,说明中国区返回的是标准 GPS 坐标。坐标系做成了环境变量 TESLA_COORD_SYSTEM,默认 wgs84。

唤醒限制写在代码里

工具说明里写了「只有用户明确要求才唤醒、不要循环调用」,但这是靠提示约束,模型偶尔会自作主张。所以又加了硬限制:

  • TESLA_ALLOW_WAKE 默认 false:无论模型怎么传参,代码都不发唤醒请求。
  • 打开后有 TESLA_WAKE_COOLDOWN_MIN(默认 30 分钟)冷却,记录写在 token 文件旁的 .lastwake,重启也不清零。

用模拟的休眠车辆测过四种情况:禁用时传 wake=True 唤醒请求为 0;放开后第一次正常唤醒;30 分钟内第二次被拦;不传 wake 不唤醒。

自检模式

python3 tesla_cn_mcp.py --test 会依次列车辆、查状态,车醒着时再查位置、给出坐标校准链接和车辆概况。自检本身不会唤醒车辆。

六、部署到 NAS 上的 Hermes

1. 找到容器能访问的目录

docker inspect hermes-agent \
  --format '{{range .Mounts}}{{.Source}}  →  {{.Destination}}{{println}}{{end}}'

我的 Hermes 数据目录挂载在容器的 /opt/data,config.yaml 也在这里。在它下面建 tesla/ 子目录,放入脚本和 token 文件。

2. 检查文件、依赖和写权限

docker exec hermes-agent ls -l /opt/data/tesla/
docker exec hermes-agent python3 -c "import mcp, httpx; print('ok')"
docker exec hermes-agent sh -c 'touch /opt/data/tesla/.w && rm /opt/data/tesla/.w && echo writable'
docker top hermes-agent -o user,pid,args | head   # 确认主进程用户能读 token 文件

目录必须可写,因为每次刷新都要写回新的 refresh\_token。

3. 配置

mcp_servers:
  tesla:
    command: "/opt/hermes/.venv/bin/python3"   # 用完整路径,原因见踩坑记录
    args: ["/opt/data/tesla/tesla_cn_mcp.py"]
    env:
      TESLA_CLIENT_ID: "<Client ID>"
      TESLA_TOKEN_FILE: "/opt/data/tesla/tesla-token.json"
      TESLA_VEHICLE_ID: "<车辆 id>"
    timeout: 90

在 Telegram 里发 /reload-mcp,看到 mcp_tesla_vehicle_location 等工具就接好了。

4. token 只留一份

在 Mac 上自检用过的 token 文件,直接拷到 NAS 继续用,之后 Mac 上不要再运行。refresh\_token 刷新一次旧的就作废,两台机器各拿一份,迟早有一边失效。同理,不要备份 token 文件,旧备份恢复回来是失效的。真丢了,重新授权两分钟。

七、踩坑记录

现象原因解决
填源 URL 报「域无效」域名还没搭起来,特斯拉会实时检查解析和证书先用 Caddy 起好 https 静态站,再回来填
换完 token 找不到车辆信息token 文件只存凭证,车辆信息要另外调 /api/1/vehicles分清「拿钥匙」和「用钥匙查车」两步
Mac 上 pip: command not found新版 Python 不允许往系统环境装包python3 -m venv 建虚拟环境再装
mcp.server.fastmcp 导入失败mcp SDK 2.x 把 FastMCP 改名为 MCPServer两种导入都试,兼容 1.x 和 2.x
重启后 Telegram 没反应Hermes 卡在连接 tesla MCP,约 5 分钟后放弃,期间消息无响应修好 MCP 后 /reload-mcp;排查时可先注释掉这段配置
MCP 报 Connection closedHermes 启动子进程只传 env 里写的变量,不传 PATH,找不到 python3command 写容器内 Python 的完整路径
定位时间显示 1943 年时间戳转换只处理了秒和毫秒两种单位自动识别秒/毫秒/微秒/纳秒,不合理的结果直接标为无效,并返回原始值

排查 MCP 启动问题时,这条命令能模拟 Hermes 的启动方式(无 PATH),看到 exit=124 说明程序正常启动、在等请求:

docker exec hermes-agent env -i TESLA_CLIENT_ID=x TESLA_TOKEN_FILE=/opt/data/tesla/tesla-token.json \
  timeout 5 /opt/hermes/.venv/bin/python3 /opt/data/tesla/tesla_cn_mcp.py; echo "exit=$?"

定位时间那个 bug 是 Hermes 自己发现的:它注意到时间不对,明确说「无法证明坐标是新鲜的」,没有硬编一个结论。这也是给工具返回原始值和「距今分钟数」的原因。

八、总结

两个 MCP 接好后,Hermes 能把「车在哪」和「怎么去」串起来回答。车醒着时随时能查;车在休眠时它会如实说明,想查就先打开特斯拉 App 把车叫醒。

几点体会:

  • 高德是一行配置的事,特斯拉是一条完整的链路:开发者应用、域名公钥、合作伙伴注册、OAuth、MCP、部署。中国区和海外完全分开,现成工具多半不能直接用。
  • 安全靠代码,不靠提示。只读权限、不写控车函数、唤醒默认禁用,这些在代码和授权层面定死,比在工具说明里叮嘱模型可靠得多。
  • 不确定的事情实测。坐标系和时间戳格式都没有猜,而是让工具把原始值和对比链接摆出来验证。
  • token 维护很省心:access\_token 自动刷新,refresh\_token 只要隔段时间用一次就一直续着。只有长期不用、改密码或撤销授权时,才需要重新走一遍授权。
Theme Jasmine by Kent Liao