告别 3006 报错！中国电信话费与流量接入 Home Assistant 全指南：新手零门槛打造全家通信资产大屏看板

想象一下这样的智慧家庭生活：清晨走出卧室，客厅走廊上的智能中控屏亮起，天气预报、室内温湿度、今日用电量一览无余；更贴心的是，全家手机的实时话费余额、当月剩余通用流量、主副卡语音分钟数整齐罗列。一旦话费低于预警线，智能音箱会温馨提醒，再也不用担心家里因宽带欠费突然断网。

然而，许多刚接触 Home Assistant 的新手在初次尝试接入电信集成时，填完手机号和服务密码，迎面而来的往往是一行冰冷的红字：未知错误，或者后台日志中赫然出现的 resultCode 3006，设备未信任。

查阅某些论坛帖子，有人轻信并推荐把掌握电信最高控制权的服务密码提交给陌生的第三方云端反代服务器。这无异于把自家门锁钥匙交给路边陌生人，带来了难以估量的隐私安全风险。

本篇教程专为 Home Assistant 新手量身定制：无需复杂的逆向背景，通过完全运行在本地局域网的零云端开源工具，只需 10 分钟，手把手带你彻底解决 3006 报错，安全合规地将全家通信资产接入 Home Assistant 大屏看板！

图 1：本文原创全景图解。展示电信官方接口直连、本地零云端授权网桥与 Home Assistant 智能中控大屏的完整闭环。

新手入门：为什么要把手机账单放上家庭大屏？

对于刚刚搭建好 Home Assistant 的朋友来说，最先接入的往往是智能灯具、人体传感器或空调开关。那么，为什么把手机通信账单接入智能家居系统，会成为家庭数字资产管理中极其重要的一环呢？

我们可以打一个非常贴切的日常生活比方：

就像我们日常开汽车，仪表盘上最重要的除了车速，就是油量表和水温表。你不需要每天打开发动机盖去测量还剩多少升汽油，仪表盘会在油量偏低时亮起醒目的黄灯，提示你该进加油站了。

在现代家庭中，通信网络就是整个数字生活的汽油。尤其是中国电信非常普遍的家庭全家桶套餐（一条千兆宽带绑定 1 张主卡和多张副卡）：

• 账户总额统一扣缴：所有手机月租、宽带费和增值业务均由主卡统一出资扣缴；
• 流量池全家共享：全家成员共享主套餐内的高速通用流量，一旦某个孩子或长辈在户外看高清视频把流量刷爆，超出部分将产生昂贵的按量计费；
• 欠费连带全家停机：一旦主卡余额不足发生扣款失败，不仅手机无法呼出呼入，家里的千兆宽带、智能门锁、安防摄像头也会因断网而瞬间陷入瘫痪！

家里的长辈和小孩往往不习惯频繁登录电信营业厅手机 App 去查询余额。而在走廊中控屏或手机 Home Assistant 界面上建立一个专属通信看板，让家庭资产透明化、自动化预警常态化，正是智能家居真正服务于生活细节的魅力所在。

新手的拦路虎：为什么只填密码会报 3006 错误？

许多新手兴冲冲地在 HACS 中搜索安装了中国电信插件，在配置窗口中认真输入了 11 位手机号和 6 位电信服务密码，满心期待点击提交，却发现弹出了红色叹号。

打开 Home Assistant 后台日志，便会看到经典的报错信息：

ERROR (MainThread) [custom_components.china_telecom.api] 
Telecom login failed: resultCode=3006, resultMsg=设备未信任, deviceId=None

与此相伴随的，是 Home Assistant 实体列表中空无一物，传感器一个都没有生成。

图 2：Home Assistant 核心日志真实截图。错误码 3006 表明电信服务端要求受信任硬件认证，未填 DeviceId 导致集成加载中断。

小学生也能听懂的银行柜台大比方

为什么明明密码输入完全正确，电信服务器却依然拒绝登录呢？我们再打一个小学生都能听懂的生活比方：

假设你去银行柜台办理大额取款或查询家庭账户总账：

• 6位服务密码：就像你在柜台口头向柜员报出的存折密码。但仅凭报出一个密码，柜员根本不敢把钱交给你，因为万一你在路上把密码小纸条弄丢了，别人捡到也能冒充你；
• DeviceId（设备硬件标识）：就像公安机关颁发给你的二代身份证原件（带有内置安全防伪芯片）。它必须在银行读卡器上实际贴卡感应，证明你坐在这个受信任的合法终端前；
• 短信验证码：就像你在柜台办业务时，银行当场向你预留手机发送的一次性确认短信。

只有当你在读卡器上感应了身份证（完成设备绑定），输入了密码，并核验了现场短信后，银行系统才会给你颁发一张长期有效的专用通行证编号（也就是电信服务端的受信任 DeviceId）。

在此之后，只要 Home Assistant 拿着这个合法的 DeviceId 和服务密码去查询余额，电信机房就会秒级放行，无需再反复折腾发短信！

图 3：通俗类比图解。将电信 DeviceId 与服务密码比作防伪身份证芯片与口头存折密码，通俗说明设备可信绑定的核心原理。

为什么千万不要使用第三方云端代验网站？

在网上搜索 3006 解决方案时，有些论坛帖子会贴出某些未知个人搭建的在线网站，号称“输入手机号、服务密码和验证码即可帮你生成 DeviceId”。

请所有新手务必牢记：这是极其危险的做法！

中国电信 6 位服务密码是电信账户的最高民用权限。一旦落入不怀好意者之手，他人可以随意登录官方营业厅查看你的通话详单、家庭宽带装机真实地址、名下绑定的亲情网号码，甚至恶意办理套餐变更与停机业务。

我们坚持的原则是：所有鉴权过程必须 100% 发生在家庭内网的本地电脑上，服务密码和短信绝不经过任何第三方云端服务器中转！

图 4：家庭宽带免密登录探测日志真实截图。抓包证实多 WAN 分流与旁路由环境下运营商专网 IP 不匹配，宽带免密通道无法稳定使用。

新手四步通关路线图：从零到大屏只需十分钟

为了让每一位新手都能无痛苦搞定，我们把接入流程提炼为最清晰的四步极速通关法。

图 5：新手极速通关四步路线图。清晰拆解准备凭证、本地提取 DeviceId、HA 添加集成以及大屏卡片呈现的完整旅程。

第一步：准备账号与服务密码

你只需准备两项最基础的信息：

1. 你的电信手机号码（11 位）；
2. 该号码对应的电信 6 位服务密码。

如果忘记了服务密码，完全不需要跑营业厅，只需在手机上打开中国电信 App，搜索重置服务密码，根据人脸或短信指引，在 1 分钟内即可重设一个新密码。

第二步：运行本地一键工具提取 DeviceId

为了让大家安全获取 DeviceId，我们开源了轻量级本地工具项目：telecom-phone-device-id-tools。

该工具基于 Python 标准库开发，完全开源透明，无需安装繁重的第三方依赖，只在本地内存运行，退出后不留任何痕迹。

你只需要在电脑或 NAS 终端中运行脚本（文末提供了 Windows 11、Ubuntu、macOS 全自动命令），终端会提示如下信息：

>>> 本地零云端授权服务已启动！
本地访问地址: http://localhost:8088
同局域网手机访问: http://LAN_IP:8088 (将 LAN_IP 替换为电脑实际 IP)

在同一 Wi-Fi 下，用手机或电脑浏览器打开该页面，界面极为清爽直观：

图 6：自研本地零云端授权工具 Web 界面真实截图。在同一局域网下舒适滑动拼图并收取短信，安全提取长效 DeviceId。

输入手机号后，页面会自动拉取电信官方的滑块拼图。滑动滑块后，点击获取短信验证码，输入手机收到的 6 位短信码，点击完成认证。页面会立刻弹出一串字母和数字组成的 DeviceId 字符串！

将其复制保存到剪贴板，随后在终端按下 Ctrl+C 关闭工具即可。

小朋友拼图大比方：为什么我们的工具滑块拼图 100% 成功？

许多人曾尝试在其他自制页面中滑块，却频繁遇到滑块偏差过大的报错。

这里有一个很有趣的小朋友贴纸生活比方：

普通的拼图纸板多大，图案就画多大，边缘一贴就准。

但电信接口下发的拼图小滑块，实际上是一张很大很大的透明塑料玻璃纸，拼图图案只画在塑料纸中间偏左的位置，四周留了一整圈肉眼看不见的透明留白空气（透明边框 Padding）。

如果按照整张透明图片的左边框去对齐大图的缺口，拼图就会活生生往右偏移了几十毫米，自然通不过校验！

图 7：滑块拼图透明通道偏移原理图解。展示离屏 Canvas 像素扫描如何过滤透明边框，纠正几何漂移。

我们在本地工具的前端中内置了基于 HTML5 Canvas 的离屏像素扫描算法，自动剔除空气边缘，量出实心拼图的绝对物理距离，因此滑块验证轻松秒过！

图 8：本地协议认证自动化测试套件执行截图。24 项端到端用例全部通过，保证了不同省份电信网关的兼容性。

第三步：在 Home Assistant 中添加并配置集成

现在我们已经拿到了三样法宝：手机号、服务密码和长效受信任 DeviceId。

打开你的 Home Assistant 网页：

1. 点击左下角配置（Settings）-> 设备与服务（Devices & Services）；
2. 点击右下角添加集成（Add Integration）；
3. 搜索并选择 China Telecom（中国电信）；
4. 在弹出的配置对话框中，逐项填入：
   • 手机号码: 你的 11 位手机号
   • 服务密码: 你的 6 位电信服务密码
   • 设备标识 (DeviceId): 粘贴刚才提取出的那串长字符串
5. 点击提交保存！

这一次，不再有 3006 报错，绿色的成功添加提示瞬间弹出！

第四步：自动生成 18 个标准传感器实体

进入 Home Assistant 开发者工具（Developer Tools）-> 状态（States），搜索 china_telecom，你会惊喜地发现，系统已经为你自动生成了 18 个全维度的标准传感器实体！

图 9：Home Assistant 开发者工具实体状态截图。涵盖通用流量、专用流量、使用率、更新时间等 18 个完整传感器。

这些实体涵盖了家庭日常关心的方方面面：

• sensor.telecom_balance: 账户当前实时话费余额（精确到分）；
• sensor.telecom_general_data_remaining: 当月通用高速流量剩余（GB）；
• sensor.telecom_general_data_used: 当月通用高速流量已用（GB）；
• sensor.telecom_voice_minutes_remaining: 当月国内免费通话剩余分钟数；
• sensor.telecom_current_month_cost: 当月累计消费金额；
• sensor.telecom_last_update: 运营商接口最新同步时间戳。

打造高颜值看板与低余额智能预警

有了真实、活跃的实体数据后，我们就可以为家庭概览 Lovelace 仪表盘配置高颜值的展示卡片，并设置贴心的自动化防欠费预警了。

图 10：Lovelace 看板卡片设计与自动化联动链路。生动展示余额仪表盘的三色阈值及低余额时的家庭音箱与手机联动。

1. 话费余额环形仪表盘卡片（Gauge）

在仪表盘页面点击右上角三个点 -> 编辑仪表盘 -> 添加卡片 -> 选择仪表盘（Gauge），或者直接在代码编辑器中粘贴如下 YAML 配置：

type: gauge
entity: sensor.telecom_balance
name: 电信账户实时余额
unit: 元
min: 0
max: 200
needle: true
severity:
  green: 50
  yellow: 20
  red: 0

配置完成后，卡片会呈现非常现代的圆环指针效果：

• 余额大于 50 元显示健康的翠绿色；
• 余额在 20 至 50 元显示醒目的橙黄色；
• 余额低于 20 元自动变为警示的红色！

2. 套餐详情与流量使用列表卡片（Entities）

如果你想在一个卡片中看清流量、通话和扣费明细，可以使用实体列表（Entities）卡片：

type: entities
title: 全家电信套餐详情
show_header_toggle: false
entities:
  - entity: sensor.telecom_balance
    name: 账户余额
    icon: mdi:wallet-outline
  - entity: sensor.telecom_general_data_remaining
    name: 剩余通用流量
    icon: mdi:wifi
  - entity: sensor.telecom_voice_minutes_remaining
    name: 剩余免费通话
    icon: mdi:phone-in-talk-outline
  - entity: sensor.telecom_current_month_cost
    name: 本月累计消费
    icon: mdi:currency-cny
  - entity: sensor.telecom_last_update
    name: 数据更新时间
    icon: mdi:clock-check-outline

图 11：Home Assistant 我的家面板真实截图。话费余额、剩余通用流量、本月消费与通话时长清晰呈现。

3. 低话费智能音箱与手机推送自动化

有了实体状态，我们来写一条贴心的自动化规则。当话费低于 20 元时，客厅音箱播放语音提醒，同时向手机推送通知：

alias: "电信话费不足 20 元温馨提醒"
description: "当主卡账户余额低于 20 元且有人在家时，联动音箱语音播报并发送手机推送"
trigger:
  - platform: numeric_state
    entity_id: sensor.telecom_balance
    below: 20
condition:
  - condition: time
    after: "08:30:00"
    before: "21:00:00"
action:
  - service: tts.speak
    target:
      entity_id: media_player.living_room_speaker
    data:
      message: "主人，电信话费余额仅剩不到 20 元，为了避免宽带停机，请及时充值哦。"
  - service: notify.notify
    data:
      title: "通信资产低余额预警"
      message: "您的电信账户余额当前为 {{ states('sensor.telecom_balance') }} 元，请及时充值。"
mode: single

有了这条自动化规则，家庭通信小管家就真正上线了。

全平台自动化脚本套件与双执行方案

为了让不同操作系统的读者都能一秒上手运行本地授权工具，我们提供了全平台脚本与两种执行方式。

人工一键自动执行指南

普通用户只需在终端复制并运行对应操作系统的脚本即可。

1. Windows 11 (PowerShell 7) 自动化脚本

以管理员权限打开 PowerShell，复制并执行以下命令：

# Telecom Auth Toolkit for Windows 11
$ErrorActionPreference = "Stop"
Write-Host ">>> 正在检查 Windows 11 本地运行环境..." -ForegroundColor Cyan

if (-not (Get-Command python -ErrorAction SilentlyContinue)) {
    Write-Error "未检测到 Python 运行环境，请先从应用商店或官网安装 Python 3.9+"
    exit 1
}

$Port = 8088
$PortActive = Get-NetTCPConnection -LocalPort $Port -ErrorAction SilentlyContinue
if ($PortActive) {
    Write-Warning "端口 $Port 已被占用，正在尝试释放..."
    Stop-Process -Id $PortActive.OwningProcess -Force -ErrorAction SilentlyContinue
}

$WorkDir = Join-Path $env:TEMP "telecom-auth-win"
if (-not (Test-Path $WorkDir)) { New-Item -ItemType Directory -Path $WorkDir | Out-Null }

Write-Host ">>> 正在启动电信本地零云端授权服务..." -ForegroundColor Green
$ScriptUrl = "https://raw.githubusercontent.com/margrop/telecom-phone-device-id-tools/main/server.py"
$LocalScript = Join-Path $WorkDir "server.py"

Invoke-WebRequest -Uri $ScriptUrl -OutFile $LocalScript
Write-Host ">>> 服务已就绪！" -ForegroundColor Yellow
Write-Host "本地电脑访问: http://localhost:$Port" -ForegroundColor White
Write-Host "同 Wi-Fi 手机访问: http://LAN_IP:$Port (将 LAN_IP 替换为电脑实际 IP)" -ForegroundColor White
Write-Host "完成验证码与短信提交后，请按 Ctrl+C 退出。" -ForegroundColor Cyan

python $LocalScript --port $Port --host localhost

2. Ubuntu 26.04 LTS (Bash) 自动化脚本

在 Linux 主机或软路由终端中执行：

#!/usr/bin/env bash
# Telecom Auth Toolkit for Ubuntu 26.04
set -euo pipefail

echo ">>> 正在检查 Ubuntu 本地环境与 Python 运行时..."
if ! command -v python3 >/dev/null 2>&1; then
    echo "正在自动安装 python3..."
    sudo apt update && sudo apt install -y python3 python3-pip
fi

PORT=8088
WORK_DIR="/tmp/telecom-auth-ubuntu"
mkdir -p "$WORK_DIR"

if lsof -Pi :$PORT -sTCP:LISTEN -t >/dev/null 2>&1; then
    echo "端口 $PORT 已被占用，正在自动清理占用进程..."
    fuser -k -n tcp $PORT || true
fi

echo ">>> 正在获取最新本地零云端授权工具核心..."
curl -fsSL "https://raw.githubusercontent.com/margrop/telecom-phone-device-id-tools/main/server.py" -o "$WORK_DIR/server.py"

echo ">>> 服务启动中..."
echo "本机访问地址: http://localhost:$PORT"
echo "局域网访问地址: http://LAN_IP:$PORT (将 LAN_IP 替换为运行主机实际 IP)"
echo "请在浏览器中完成拼图与短信验证，完成后按 Ctrl+C 退出即可。"

python3 "$WORK_DIR/server.py" --port "$PORT" --host localhost

3. macOS 27 (Zsh) 自动化脚本

在 Mac 终端中直接执行：

#!/usr/bin/env zsh
# Telecom Auth Toolkit for macOS 27
set -e

echo ">>> 正在检查 macOS 本地开发环境..."
if ! command -v python3 >/dev/null 2>&1; then
    echo "未检测到 Python3，请通过 Xcode 命令行工具或 Homebrew 安装。"
    exit 1
fi

PORT=8088
WORK_DIR="/tmp/telecom-auth-macos"
mkdir -p "$WORK_DIR"

if lsof -Pi :$PORT -sTCP:LISTEN -t >/dev/null 2>&1; then
    echo "检测到端口 $PORT 被占用，正在释放..."
    kill -9 $(lsof -t -i:$PORT) 2>/dev/null || true
fi

echo ">>> 下载并启动电信本地受信任授权套件..."
curl -fsSL "https://raw.githubusercontent.com/margrop/telecom-phone-device-id-tools/main/server.py" -o "$WORK_DIR/server.py"

echo ">>> 本地授权服务已就绪！"
echo "Mac 浏览器访问: http://localhost:$PORT"
echo "同 WiFi 手机访问: http://LAN_IP:$PORT (将 LAN_IP 替换为 Mac 实际 IP)"
echo "完成验证并获取 DeviceId 后，在终端按 Ctrl+C 退出。"

python3 "$WORK_DIR/server.py" --port "$PORT" --host localhost

AI Agent 自动化配置工作流

如果你在使用 Claude、Cursor、Codex 或其他本地 AI 辅助 Agent，可以直接将以下提示词发送给你的 Agent，让其全自动化替你配置：

请帮我执行中国电信 DeviceId 授权工具：
1. 检查本地环境 Python 3 版本与网络连通性；
2. 启动 telecom-auth 脚本，监听 8088 端口；
3. 输出可供手机访问的局域网授权 URL；
4. 捕获用户在 Web 页面完成滑块与短信鉴权后返回的 DeviceId；
5. 自动将其写入 Home Assistant 的配置条目中，并调用 API 验证数据采集正常。

Agent 会自动帮你拉起守护服务，捕获凭证，并在配置完成后优雅退出进程。

新手排障速查手册与常见疑问解答

遇到偶发问题不要慌，我们整理了一份对号入座的速查决策树与问答清单。

图 12：原创排障决策树矩阵。汇总 3006 报错、滑块位移偏差、刚添加实体 unknown 与主副卡添加的快速诊断逻辑。

问：获取一次 DeviceId 后，有效期有多长？后续还需要每月发短信吗？

答：完全不需要！中国电信官方签发的 DeviceId 属于长效硬件受信任绑定凭证。在运营商不发生极其重大的全网风控重构的前提下，该凭证通常长期有效（数月至数年）。日常每小时的后台轮询只需要使用 DeviceId 配合服务密码完成静默认证，无需再次人工接收短信。

问：既然已经有了 DeviceId，为什么还需要电信服务密码？

答：正如我们前面的银行柜员比方：DeviceId 是二代身份证读卡芯片（证明设备合法），服务密码是口头密码（证明业务知情）。电信网关要求两者同时出示，以防止单点凭证被盗用，构成了双因子安全保障。

问：家庭宽带绑定的主副卡套餐，如何同时监控多张手机卡？

答：非常简单！在 Home Assistant 的集成页面中，中国电信集成支持添加多个条目（Config Entries）。你可以分别为主卡和每张副卡在本地工具中获取一次专属 DeviceId，然后依次添加到集成中。主卡条目负责展示全家共享账户余额与总流量，副卡条目负责展示各自独立的通话消耗与副卡流量，多账号之间在后台自动排队同步，互不冲突！

问：刚配置完集成，为什么所有实体都显示未知（unknown）？

答：这是完全正常的现象！为了防止 Home Assistant 在系统重启时因网络卡顿而崩溃，现代集成采用了先占座、后入席的宽容设计：集成在启动瞬间先在系统中注册 18 个实体占位符，然后后台异步任务会向电信服务器发起数据拉取。通常等待 30 至 60 秒钟，首次数据同步完成，所有数值就会自动点亮呈现！

问：这个项目支持中国移动或中国联通吗？

答：本项目专注解决中国电信独特的 3006 设备未信任与滑块短信协议链。对于中国联通，社区方案通常依赖微信小程序的抓包；对于中国移动，目前我们实现了通过抓包提取自动登录会话的方式接入。三家运营商的安全鉴权体系各不相同。

开源致谢与参考资料

• margrop/telecom-phone-device-id-tools：本文配套实现的中国电信 DeviceId 本地零云端设备授权工具官方开源仓库。
• 中国电信官方登录网关接口协议：本次协议契约对齐的官方基础。
• hlhk2017/ChinaTelecomMonitor-Homeassistant-Integration：本项目优化的基础集成原型。
• Home Assistant 官方架构指南：Config Entries：实体生命周期与异步刷新设计规范。
• W3C Canvas 2D Context 规范：离屏 ImageData 像素扫描标准。

本文所涉及的六张真实截图均采集自本人家庭真实运行环境，已隐去完整 IP、内部主机名与手机号码；六张原创架构图与图表均为矢量绘制。