常见问题排查

本文档涵盖使用 AmebaClaw 过程中最常见的问题，按问题类型分类整理，每个问题均提供症状描述、可能原因及详细解决步骤。建议初次使用者从第一章开始顺序排查。

备注

在排查任何问题前，建议先通过串口连接设备查看实时日志，往往能直接定位原因。串口监控命令：

python ameba.py monitor -p /dev/ttyUSB0 -b 1500000

烧录与启动问题

找不到 AmebaClaw-XXXX 热点

症状

设备通电后，使用手机或电脑扫描周边 Wi-Fi 列表，找不到名为 AmebaClaw-XXXX 格式的热点（其中 XXXX 为设备 MAC 地址后四位）。

可能原因

  • 设备未正常启动，或 USB 供电不足

  • 固件尚未烧录，或烧录不完整

  • 设备已完成过 Wi-Fi 配置，不再广播 SoftAP 热点（正常行为）

解决步骤

  1. 确认供电正常

    检查 USB 线是否插紧，建议使用电脑 USB 3.0 端口或独立 5V/1A 以上电源适配器。避免使用低质量充电线（仅供电无数据线）。

  2. 观察设备指示灯

    正常启动时设备 LED 会有闪烁动作，若完全无反应则需检查供电或重新烧录固件。

  3. 连接串口查看启动日志

    python ameba.py monitor -p /dev/ttyUSB0 -b 1500000

    观察日志输出。若无任何输出，说明固件未烧录或设备故障；若看到启动信息但无 SoftAP 相关日志，说明固件异常。

  4. 设备已配置过 Wi-Fi 的情况

    若设备曾连接过 Wi-Fi，启动后会直接尝试连接已保存的网络，不会再广播热点。此时可通过串口发送 AT 指令清除 Wi-Fi 配置，使设备重新进入 SoftAP 模式：

    AT+CLAW=wifi,clear

    发送后重启设备，即可重新看到 AmebaClaw-XXXX 热点。

  5. 重新烧录固件

    若以上步骤均无效，访问在线烧录工具重新烧录完整固件。

小技巧

SoftAP 热点名称为 AmebaClaw-XXXX，默认无密码，直接连接即可。连接后打开浏览器访问 192.168.1.1 进入 Web 后台进行配置。

在线烧录工具无法连接设备

症状

打开在线烧录工具页面后，点击"连接设备"按钮，弹出端口选择对话框但找不到设备，或对话框根本不弹出。

可能原因

  • 浏览器不支持 Web Serial API（非 Chromium 内核浏览器）

  • USB 转串口驱动未安装（Windows 系统常见问题）

  • USB 数据线仅支持充电，不支持数据传输

  • 设备未被操作系统识别

解决步骤

  1. 更换支持 Web Serial 的浏览器

    Web Serial API 仅在 Chromium 内核浏览器中可用。请使用 Google Chrome 89+ 或 Microsoft Edge 89+，不支持 Firefox、Safari 等浏览器。

  2. 安装 USB 转串口驱动（Windows）

    AmebaClaw 开发板通常使用 CH340 或 CP210x 芯片。请根据实际芯片安装对应驱动：

    • CH340/CH341：安装 WCH 官方驱动

    • CP210x：安装 Silicon Labs 官方驱动

    安装驱动后，在设备管理器中确认"端口 (COM 和 LPT)"下出现新的 COM 端口。

  3. 确认使用数据线而非充电线

    部分 USB 线仅有充电功能，无数据传输能力。更换带数据传输功能的 USB 线后重试。

  4. 重新插拔 USB

    拔出 USB 线，等待 3 秒后重新插入，等待操作系统完成驱动加载，再尝试连接。

  5. Linux 用户添加串口权限

    sudo usermod -aG dialout $USER

    退出并重新登录后生效。

备注

macOS 用户通常无需额外安装驱动，若 CH340 无法识别可尝试安装 WCH macOS 驱动。

烧录中途失败

症状

烧录进度条中途停止，页面提示错误，如"写入失败"、"校验错误"或"连接中断"。

可能原因

  • USB 线接触不良或供电抖动

  • USB 端口电流不足

  • 串口连接被其他程序占用

  • 固件文件下载不完整

解决步骤

  1. 断开设备并重新连接

    关闭当前烧录工具页面，拔出 USB 线，等待 5 秒后重新插入，刷新页面重新操作。

  2. 确保没有其他程序占用串口

    关闭所有串口监控工具（如串口助手、minicom、ameba.py monitor 等），确保只有烧录工具在使用串口。

  3. 重新点击"开始烧录"

    不需要重新下载固件文件，直接点击烧录按钮重试即可。

  4. 更换 USB 线和端口

    优先使用电脑背板的 USB 3.0 端口，避免使用 USB Hub。更换经过认证的高质量数据线。

  5. 如持续失败，尝试不同电脑

    排除本机环境问题（驱动兼容性、USB 控制器问题等）。

警告

烧录中途失败可能导致固件不完整，设备可能无法正常启动。重新完整烧录一次可恢复正常状态。

网络配置问题

Wi-Fi 连接失败

症状

在 Web 后台输入 Wi-Fi SSID 和密码后保存，设备重启后仍未连接到路由器，串口日志显示连接失败或反复重试。

可能原因

  • SSID 或密码输入有误（注意大小写和特殊字符）

  • 路由器使用 5GHz 频段，AmebaClaw 仅支持 2.4GHz

  • 路由器开启了"AP 隔离"或"客户端隔离"功能

  • 信号强度过弱

解决步骤

  1. 核对 SSID 和密码

    Wi-Fi 名称（SSID）和密码均区分大小写。建议在手机或其他设备上先连接同一网络验证密码无误，再填入 Web 后台。

  2. 确认使用 2.4GHz 频段

    AmebaClaw 仅支持 2.4GHz Wi-Fi。若路由器设置了双频合一（2.4G 和 5G 使用同一 SSID），设备通常可自动选择 2.4GHz；但若路由器仅提供 5GHz 网络，则无法连接。请在路由器管理页面确认 2.4GHz 已开启。

  3. 检查路由器 AP 隔离设置

    部分路由器（尤其是公共网络、企业网络或一些家用路由器的访客网络）开启了"AP 隔离"或"无线隔离"功能，导致同一 Wi-Fi 下的设备之间无法互访。请在路由器管理页面关闭此功能，或改用不隔离的网络。

  4. 确认信号强度

    将设备移近路由器，排除信号问题后再测试。

  5. 通过串口查看详细错误

    python ameba.py monitor -p /dev/ttyUSB0 -b 1500000

    观察日志中 Wi-Fi 连接相关的错误信息，可获得更具体的失败原因。

  6. 重新配置 Wi-Fi

    若多次失败，先清除已保存的 Wi-Fi 配置再重新配置：

    AT+CLAW=wifi,clear

联网成功但无法打开 Web 后台

症状

串口日志显示设备已成功连接 Wi-Fi 并获得 IP 地址，但在浏览器中输入该 IP 地址无法打开 Web 后台页面，或页面加载超时。

可能原因

  • 电脑和设备不在同一局域网

  • 电脑防火墙阻止了访问

  • 浏览器缓存问题

  • 端口被占用或访问方式有误

解决步骤

  1. 确认电脑与设备在同一局域网

    电脑必须连接到与 AmebaClaw 相同的 Wi-Fi 网络。如果电脑使用有线网络，而设备连接 Wi-Fi，需要确认两者属于同一网段（通常由同一路由器管理即可）。

  2. 使用正确的 IP 地址和端口访问

    在浏览器地址栏输入设备 IP，默认端口为 80，直接输入 IP 即可：

    http://192.168.x.x

    不要使用 HTTPS（https://），也不要加端口号（除非日志中有特别说明）。

  3. 临时关闭电脑防火墙测试

    Windows 防火墙或第三方安全软件可能阻止访问局域网内设备。临时关闭防火墙后再次尝试访问，若成功则需在防火墙中添加例外规则。

  4. 清除浏览器缓存

    按 Ctrl+Shift+R（Windows/Linux）或 Cmd+Shift+R（macOS）强制刷新，或使用无痕模式访问。

  5. 尝试 ping 设备

    ping 192.168.x.x

    若 ping 不通，说明网络连通性存在问题，排查步骤 1 中的网络隔离问题。

不知道设备 IP 地址

症状

设备已连接 Wi-Fi，但不清楚设备被分配到的 IP 地址，无法访问 Web 后台。

解决步骤

  1. 通过串口日志查看 IP

    连接串口后重启设备，在启动日志中查找类似以下内容：

    [WIFI] IP address: 192.168.1.xxx

    python ameba.py monitor -p /dev/ttyUSB0 -b 1500000

  2. 通过 AT 指令查询当前网络配置

    在串口终端发送以下指令查看当前 Wi-Fi 及 IP 信息：

    AT+CLAW=cfg

    返回信息中会包含当前连接的 Wi-Fi 名称和 IP 地址。

  3. 查看路由器 DHCP 分配列表

    登录路由器管理页面（通常为 192.168.1.1 或 192.168.0.1），在 DHCP 客户端列表中查找设备名称（通常包含 "Ameba" 或 "Realtek"）对应的 IP 地址。

  4. 使用网络扫描工具

    使用 nmap 或手机 App（如 Fing）扫描局域网内在线设备，找到 AmebaClaw 对应的 IP：

    nmap -sn 192.168.1.0/24

AI 对话问题

发送消息后无回复或超时

症状

在 Web 后台实时对话页面或通过消息机器人发送消息后，长时间没有任何回复，或提示"请求超时"。

可能原因

  • LLM 服务未配置或配置有误

  • API Key 错误或已过期

  • 设备网络连接不稳定

  • LLM 服务商接口暂时不可用

解决步骤

  1. 检查 LLM 配置

    进入 Web 后台 → LLM 配置，确认以下项目均已正确填写：

    • API Base URL（服务商接口地址）

    • API Key

    • 模型名称（Model ID）

    • 认证方式（需与服务商匹配）

  2. 验证 API Key 有效性

    在电脑上使用 curl 命令测试 API Key 是否有效：

    curl -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     https://api.your-provider.com/v1/models

    若返回模型列表则 Key 有效；若返回 401 错误则 Key 无效或已过期。

  3. 确认设备网络正常

    在串口终端确认设备 Wi-Fi 连接状态，或通过 Web 后台实时日志查看网络请求情况。

  4. 检查 API 服务商状态

    访问服务商官方状态页面，确认当前服务是否正常。如遇服务商故障，等待其恢复后重试。

  5. 检查网络访问限制

    部分地区可能无法直接访问某些 LLM 服务商接口，需要确认设备所在网络环境是否可正常访问目标 API 地址。

回复乱码或错误语言

症状

AI 回复内容语言不符合预期（如应该用中文却用英文回复），或回复中出现乱码字符。

可能原因

  • Agent 未指定回复语言偏好

  • USER.md 文件中未设置用户语言偏好

  • 模型对语言的理解依赖上下文

解决步骤

  1. 直接在对话中告知 Agent

    最简单的方式是直接告诉 Agent 使用中文回复：

    请你之后都用中文回复我

    Agent 会记住这一偏好并在后续对话中保持。

  2. 在 USER.md 中设置语言偏好

    进入 Web 后台 → 文件管理，编辑 USER.md 文件，在文件开头或描述部分加入语言偏好说明：

    # 用户偏好
- 请始终使用简体中文回复
- 技术术语可保留英文原文，但说明文字使用中文

    保存后，Agent 在每次对话初始化时会读取此文件作为上下文。

  3. 排除乱码问题

    若出现乱码（非语言问题），检查：

    • Web 后台页面编码是否为 UTF-8（浏览器中查看页面源码确认）

    • 消息机器人平台（Telegram/微信）对 Unicode 字符的支持情况

提示"模型不存在"或"认证失败"

症状

AI 对话时返回错误提示，如 model not found、invalid model、authentication failed、unauthorized 等。

可能原因

  • 模型 ID 拼写错误（区分大小写）

  • 使用了服务商不支持的模型名称

  • 认证方式与服务商要求不匹配

  • API Key 格式不正确

解决步骤

  1. 核对 Model ID 名称

    模型 ID 区分大小写，且不同服务商的命名格式不同。请从服务商官方文档中复制准确的模型 ID，例如：

    服务商

    示例模型 ID

    Anthropic

    claude-opus-4-5、claude-sonnet-4-5

    OpenAI

    gpt-4o、gpt-4o-mini

    DeepSeek

    deepseek-chat、deepseek-reasoner

  2. 检查认证方式

    不同服务商使用不同的认证方式：

    • Anthropic：必须在 LLM 配置中选择 Anthropic 认证方式，使用 x-api-key 头部

    • OpenAI 兼容接口：选择标准 Bearer Token 认证方式

    在 Web 后台 → LLM 配置 中确认认证方式与服务商文档一致。

  3. 检查 API Key 格式

    确认 API Key 复制完整，没有多余空格或换行符。不同服务商 Key 格式不同（如 Anthropic 以 sk-ant- 开头，OpenAI 以 sk- 开头）。

  4. 测试 API 连通性

    使用服务商文档中的示例 curl 命令，在电脑上测试 Key 是否可用，排除 Key 本身的问题。

回复截断或内容不完整

症状

AI 回复明显被切断，内容不完整，或长篇回复只输出了开头部分就停止了。

可能原因

  • 最大 Token 数限制过低

  • 模型达到输出长度上限

解决步骤

  1. 增大最大 Token 数限制

    进入 Web 后台 → LLM 配置 → 高级设置，找到"最大 Token 数"（Max Tokens）参数，将其调大。建议设置为 2048 或 4096，具体上限取决于所使用的模型。

  2. 确认模型支持的最大输出长度

    查阅服务商文档，了解所用模型的 max_output_tokens 限制，不要超过该值。

  3. 对话中提示续写

    若某次回复已截断，可直接发送"请继续"，Agent 会从截断处继续输出。

小技巧

增大 Max Tokens 会增加单次 API 调用费用，建议根据实际需求合理设置，一般任务 1024～2048 已足够。

Lua Skill 问题

Skill 执行报错 "module not found"

症状

Agent 执行 Lua Skill 时，返回错误信息包含 module not found、module 'xxx' not found 等，Skill 执行失败。

可能原因

  • Skill 中使用了仅在 REPL 模式下可用的硬件模块

  • 部分硬件模块（wifi、spi、uart、pwm、ir、lcdc、adc、thermal、touch 等）出于安全和资源管理原因，在 Skill 沙箱中不可直接 require

解决步骤

  1. 检查 Skill 中使用的模块

    检查 Lua Skill 代码，确认是否 require 了以下不可在 Skill 中使用的模块：

    wifi, spi, uart, pwm, ir, lcdc, adc, thermal, touch

  2. 改用 REPL 模式执行

    对于需要使用上述硬件模块的任务，改用 AT 指令的 Lua REPL 模式：

    AT+CLAW=lua

    进入 REPL 模式后，可直接 require 硬件模块并执行代码。

  3. 告知 Agent 使用 REPL 模式

    直接告诉 Agent 改变执行方式：

    请改用 REPL 模式执行这段 Lua 代码

    Agent 会自动切换到合适的执行方式。

备注

Skill 模式适合无状态的、不依赖硬件底层的任务（如数据处理、HTTP 请求、格式转换等）。硬件控制类任务请使用 REPL 模式或通过专用 Skill 接口封装。

GPIO 控制无效 / 引脚不对

症状

Agent 编写的 Lua 代码执行了 GPIO 控制，但实际硬件（LED、继电器等）没有响应，或控制的是错误的引脚。

可能原因

  • GPIO 编号与实际物理引脚连接不对应

  • 未确认开发板的实际引脚功能分配

  • 引脚可能被其他功能占用

解决步骤

  1. 激活 board_hardware_info Skill 查询引脚信息

    在对话中告诉 Agent：

    激活 board_hardware_info 查询可用引脚及其功能

    Agent 会调用该 Skill 获取当前开发板的引脚映射表，包括每个引脚支持的功能（GPIO/ADC/PWM/SPI/I2C 等）。

  2. 根据查询结果修正引脚编号

    获取到引脚信息后，告诉 Agent：

    板上 LED 连接到哪个引脚？请用正确的引脚编号重写控制代码

  3. 确认引脚方向和初始电平

    在控制 GPIO 前，确保代码中正确设置了引脚方向（输入/输出）和初始电平。

  4. 检查引脚占用情况

    部分引脚在系统初始化时已被 UART（串口日志）、SPI（Wi-Fi）等功能占用，强行作为 GPIO 使用会失效。查询引脚信息时注意 "occupied" 或 "reserved" 标注。

Skill 运行超时

症状

Agent 执行 Lua Skill 时，返回超时错误，任务未完成就被终止。通常在执行包含延时循环、持续监控或长时间等待的 Skill 时出现。

可能原因

  • lua_run 模式有 30 秒超时限制

  • Skill 代码中包含长时间的 sleep 循环或等待逻辑

解决步骤

  1. 了解超时限制

    • lua_run：同步执行，最长 30 秒，适合短任务

    • lua_run_async：异步执行，适合长时间运行的后台任务

  2. 告知 Agent 改用异步模式

    在对话中描述需求，让 Agent 重写 Skill：

    这个任务需要持续运行，请将 Skill 改写为异步版本，使用 lua_run_async 执行

  3. 重构长时间任务为事件驱动

    对于周期性任务，建议使用定时器（timer）而非 sleep 循环，减少资源占用：

    -- 推荐：使用定时器
local timer = require("timer")
timer.create(1000, function()
    -- 每 1000ms 执行一次
end)

-- 不推荐：在 lua_run 中使用 sleep 循环
while true do
    do_something()
    os.sleep(1000)  -- 会导致超时
end

小技巧

长期后台任务（如持续监控传感器、保持消息推送）应始终使用 lua_run_async，lua_run 仅用于一次性、短时执行的任务。

消息机器人问题

Telegram 机器人无响应

症状

通过 Telegram 向机器人发送消息，机器人长时间没有任何回复，或以前正常但突然停止响应。

可能原因

  • Bot Token 配置错误或已失效

  • 未向机器人发送 /start 命令（首次使用必须）

  • 设备网络连接中断

  • Telegram API 在当前网络环境不可访问

解决步骤

  1. 确认 Bot Token 配置正确

    进入 Web 后台 → 消息机器人配置 → Telegram，核对 Bot Token 是否完整且无多余空格。Bot Token 格式为 1234567890:AAXXXXXX...（数字 + 冒号 + 字母数字串）。

  2. 向机器人发送 /start 命令

    若是第一次使用该机器人，必须先在 Telegram 中搜索机器人用户名，点击"开始"或发送 /start 命令激活会话。Telegram 出于安全机制，机器人不能主动发消息给未发起对话的用户。

  3. 检查设备联网状态

    通过串口日志确认设备 Wi-Fi 连接正常，且能访问外网。

  4. 检查网络对 Telegram 的可访问性

    部分网络环境（企业网络、特定地区）可能无法访问 Telegram API（api.telegram.org）。可在电脑上测试：

    curl https://api.telegram.org/bot<YOUR_TOKEN>/getMe

    若无法访问，需解决网络访问问题。

  5. 重新保存配置并重启

    在 Web 后台重新保存 Telegram 配置，然后重启设备（通过 Web 后台或断电重启）。

微信扫码后状态不变

症状

在 Web 后台配置微信机器人后，用微信扫描二维码，但 Web 后台的状态一直显示"未连接"或"等待扫码"，扫码后无任何变化。

可能原因

  • iLink URL 配置错误

  • 二维码已过期或未正确生成

  • 配置未保存就尝试扫码

  • 设备未联网，无法与 iLink 服务器通信

解决步骤

  1. 确认 iLink URL 正确

    微信机器人通过 iLink 平台接入。确认 Web 后台中填写的 iLink URL 正确，通常为：

    https://ilinkai.weixin.qq.com

    注意使用 HTTPS，不要遗漏路径或添加多余斜杠。

  2. 保存配置后重新生成二维码

    先点击"保存"按钮保存配置，然后点击"重新生成二维码"或刷新页面，获取最新二维码再扫码。

  3. 使用微信扫码后等待片刻

    扫码后状态更新可能有 5～10 秒延迟，请耐心等待，不要立即刷新页面。

  4. 重启设备后重试

    保存配置后通过 Web 后台或断电重启设备，重启完成后重新生成二维码并扫码：

    AT+CLAW=reboot

  5. 检查设备网络

    设备必须能访问 iLink 服务器才能完成微信机器人的认证流程。确认设备 Wi-Fi 连接正常且可访问外网。

恢复出厂设置

当设备出现无法通过常规方式解决的问题，或需要重新从零配置时，可通过以下步骤将设备恢复至出厂状态。

恢复项目与对应指令

恢复项目

AT 指令

说明

清除 Wi-Fi 配置

AT+CLAW=wifi,clear

下次启动进入 SoftAP 热点模式

清除所有会话历史

AT+CLAW=session,clear,all

清除 Agent 的所有对话记录

清除长期记忆

AT+CLAW=memory,clear

清除 Agent 积累的用户偏好记忆

完整恢复步骤

  1. 通过串口发送 AT 指令（按需选择）

    AT+CLAW=wifi,clear
AT+CLAW=session,clear,all
AT+CLAW=memory,clear

  2. 通过 Web 后台恢复默认文件

    进入 Web 后台 → 文件管理，找到被修改过的系统文件（如 AGENTS.md、SOUL.md、USER.md 等），点击"恢复默认"将其还原为出厂内容。

  3. 重新烧录固件（最彻底的方式）

    若以上步骤无法解决问题，或需要更新到最新固件，可通过在线烧录工具重新烧录完整固件，这将彻底清除所有用户数据。

警告

恢复出厂设置后，以下所有数据均会永久丢失且无法恢复：

  • Wi-Fi 连接配置

  • LLM API Key 及模型配置

  • 所有 Agent 对话历史

  • Agent 积累的长期记忆

  • 自定义的 Skill 和配置文件

请在操作前确认您已记录所有重要配置信息（尤其是 API Key）。

获取帮助

当本文档无法解决您的问题时，以下渠道可提供进一步支持。

查看设备实时日志

串口日志是排查问题最直接的手段，几乎所有异常都会在日志中留下记录：

python ameba.py monitor -p /dev/ttyUSB0 -b 1500000

将观察到的错误信息复制下来，有助于在社区或 Issue 中准确描述问题。

直接询问 Agent

AmebaClaw 的 Agent 本身具备自我诊断能力。在 Web 后台 → 实时对话 中，可以直接向 Agent 提问：

最近的日志里有没有错误？
Wi-Fi 连接为什么失败？
帮我检查一下 LLM 配置是否正确

Agent 会读取系统状态和日志，给出诊断建议。

GitHub Issues

在以下地址提交问题报告或查找已知问题的解决方案：

https://github.com/Ameba-AIoT/ameba-claw

提交 Issue 时请包含以下信息：

  • 使用的固件版本（可在 Web 后台或串口启动日志中查看）

  • 问题的详细描述和复现步骤

  • 串口日志中的相关错误信息

  • 已尝试的排查步骤

小技巧

提交 Issue 前，先在 Issues 列表中搜索关键词，可能已有其他用户遇到相同问题并找到了解决方案。