Troubleshooting

This document covers the most common issues encountered when using AmebaClaw, organized by problem type. Each entry describes the symptom, lists likely causes, and provides step-by-step resolution guidance. First-time users are encouraged to work through sections in order.

Note

Before investigating any issue, connect to the device over serial and monitor live logs. Logs often reveal the root cause immediately. Serial monitor command:

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

Flash & Boot Issues

Cannot Find the AmebaClaw-XXXX Hotspot

Symptom

After powering on the device, scanning for nearby Wi-Fi networks on a phone or computer does not show a hotspot named AmebaClaw-XXXX (where XXXX is the last four characters of the device MAC address).

Likely Causes

  • The device has not booted successfully, or USB power is insufficient

  • Firmware has not been flashed, or the flash was incomplete

  • The device has already been configured with Wi-Fi credentials and is no longer broadcasting the SoftAP hotspot (this is normal behavior)

Resolution Steps

  1. Confirm the power supply is adequate

    Check that the USB cable is firmly connected. Use a USB 3.0 port on a computer or a dedicated 5 V / 1 A (or higher) power adapter. Avoid charge-only cables that carry no data.

  2. Observe the device indicator LED

    During a normal boot the LED blinks. If there is no activity at all, check the power supply or re-flash the firmware.

  3. Connect via serial and read the boot log

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

    If there is no output whatsoever, the firmware is not present or the device is faulty. If you see boot messages but no SoftAP-related lines, the firmware may be corrupted.

  4. Device has previously been configured with Wi-Fi

    If the device has already connected to a network, it will attempt to reconnect to the saved network on boot rather than broadcasting a hotspot. Clear the saved Wi-Fi configuration via AT command to return to SoftAP mode:

    AT+CLAW=wifi,clear

    Restart the device after sending the command. The AmebaClaw-XXXX hotspot will reappear.

  5. Re-flash the firmware

    If the steps above do not help, use the online flash tool to write a complete firmware image.

Tip

The SoftAP hotspot name is AmebaClaw-XXXX and has no password — connect directly. Once connected, open a browser and navigate to 192.168.1.1 to access the Web admin panel.

Online Flash Tool Cannot Connect to the Device

Symptom

After opening the online flash tool page and clicking “Connect Device”, the port selection dialog does not appear, or appears but lists no device.

Likely Causes

  • The browser does not support the Web Serial API (non-Chromium browsers)

  • The USB-to-serial driver is not installed (common on Windows)

  • The USB cable supports charging only and does not carry data

  • The operating system has not recognized the device

Resolution Steps

  1. Switch to a browser that supports Web Serial

    The Web Serial API is only available in Chromium-based browsers. Use Google Chrome 89+ or Microsoft Edge 89+. Firefox and Safari are not supported.

  2. Install the USB-to-serial driver (Windows)

    AmebaClaw boards typically use a CH340 or CP210x chip. Install the corresponding driver:

    • CH340 / CH341: Install the official WCH driver

    • CP210x: Install the official Silicon Labs driver

    After installation, open Device Manager and confirm that a new COM port appears under “Ports (COM & LPT)”.

  3. Confirm you are using a data-capable cable

    Some USB cables can only deliver power and cannot transfer data. Replace the cable with one that explicitly supports data transfer and try again.

  4. Re-seat the USB connection

    Unplug the USB cable, wait 3 seconds, plug it back in, and allow the operating system to finish loading the driver before retrying.

  5. Grant serial port permission on Linux

    sudo usermod -aG dialout $USER

    Log out and log back in for the change to take effect.

Note

macOS users generally do not need to install a separate driver. If a CH340 device is not recognized, try installing the WCH macOS driver.

Flash Fails Midway

Symptom

The flash progress bar stops partway through. The page reports an error such as “write failed”, “verification error”, or “connection lost”.

Likely Causes

  • Loose USB connection or unstable power

  • Insufficient current from the USB port

  • The serial port is already in use by another application

  • The firmware file download was incomplete

Resolution Steps

  1. Disconnect and reconnect the device

    Close the current flash tool page, unplug the USB cable, wait 5 seconds, plug it back in, refresh the page, and start again.

  2. Ensure no other application is using the serial port

    Close all serial monitoring tools (serial assistants, minicom, ameba.py monitor, etc.) before flashing. Only one application can hold the serial port at a time.

  3. Click “Start Flash” again

    You do not need to re-download the firmware file. Simply click the flash button to retry.

  4. Try a different USB cable and port

    Prefer the USB 3.0 ports on the back panel of a desktop computer. Avoid USB hubs. Use a certified, high-quality data cable.

  5. If failures persist, try a different computer

    This rules out local environment issues such as driver incompatibilities or USB controller problems.

Warning

A failed mid-flash leaves the firmware in an incomplete state. The device may not boot normally. Re-flashing a complete firmware image will restore it.

Network Issues

Wi-Fi Connection Fails

Symptom

After entering the Wi-Fi SSID and password in the Web admin panel and saving, the device restarts but does not connect to the router. Serial logs show repeated connection failures or retry loops.

Likely Causes

  • The SSID or password was entered incorrectly (both are case-sensitive)

  • The router is broadcasting only on the 5 GHz band; AmebaClaw supports 2.4 GHz only

  • The router has “AP isolation” or “client isolation” enabled

  • Signal strength is too weak

Resolution Steps

  1. Double-check the SSID and password

    Wi-Fi credentials are case-sensitive. Verify the password is correct by connecting another device to the same network first, then re-enter the credentials in the Web admin panel.

  2. Confirm the 2.4 GHz band is available

    AmebaClaw only supports 2.4 GHz Wi-Fi. If the router uses a unified dual-band SSID, the device usually selects 2.4 GHz automatically. However, if the router provides only a 5 GHz network, the device cannot connect. Log in to the router admin page and confirm that the 2.4 GHz radio is enabled.

  3. Disable AP isolation on the router

    Some routers — especially those serving guest networks, corporate environments, or certain home router configurations — enable “AP isolation” or “wireless isolation”, which prevents devices on the same Wi-Fi network from communicating with each other. Disable this setting in the router admin page, or connect the device to a network that does not isolate clients.

  4. Move the device closer to the router

    Rule out signal strength as a factor before investigating further.

  5. Read detailed error messages from serial output

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

    Look for Wi-Fi connection error messages in the log for more specific failure information.

  6. Clear saved Wi-Fi and reconfigure

    If multiple attempts fail, clear the stored credentials before trying again:

    AT+CLAW=wifi,clear

Connected to Wi-Fi but Cannot Open the Web Admin Panel

Symptom

Serial logs confirm that the device has joined the Wi-Fi network and received an IP address, but entering that IP address in a browser either times out or fails to load the admin panel.

Likely Causes

  • The computer and the device are not on the same local network

  • A firewall on the computer is blocking access

  • A browser cache issue

  • Incorrect URL or port

Resolution Steps

  1. Confirm the computer is on the same local network as the device

    The computer must be connected to the same Wi-Fi network as AmebaClaw. If the computer uses a wired connection, verify that both the wired and wireless networks are managed by the same router and share the same subnet.

  2. Use the correct URL format

    Enter the device IP address in the browser address bar. The default port is 80; no port number is needed:

    http://192.168.x.x

    Do not use HTTPS (https://) and do not append a port number unless the log explicitly states otherwise.

  3. Temporarily disable the computer firewall for testing

    Windows Firewall or third-party security software may block access to devices on the local network. Temporarily disable the firewall and retry. If that fixes the issue, add an exception rule rather than leaving the firewall off.

  4. Force-refresh the browser or use a private window

    Press Ctrl+Shift+R (Windows / Linux) or Cmd+Shift+R (macOS) to bypass the cache, or open the URL in a private/incognito window.

  5. Ping the device to verify basic connectivity

    ping 192.168.x.x

    If the ping fails, there is a network-level connectivity problem. Return to step 1 and investigate network isolation.

Unknown Device IP Address

Symptom

The device has connected to Wi-Fi successfully, but you do not know the IP address assigned to it and cannot access the Web admin panel.

Resolution Steps

  1. Read the IP address from the serial boot log

    Connect via serial, restart the device, and look for a line similar to the following in the output:

    [WIFI] IP address: 192.168.1.xxx

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

  2. Query the current network configuration via AT command

    In the serial terminal, send the following command to display the current Wi-Fi and IP information:

    AT+CLAW=cfg

    The response includes the connected SSID and the device IP address.

  3. Check the router DHCP client list

    Log in to the router admin page (typically 192.168.1.1 or 192.168.0.1) and find the DHCP client list. Look for a device name containing “Ameba” or “Realtek” and note its IP address.

  4. Use a network scanning tool

    Use nmap or a mobile app such as Fing to scan for active devices on the local network:

    nmap -sn 192.168.1.0/24

AI Conversation Issues

No Reply After Sending a Message, or Request Times Out

Symptom

After sending a message from the Web admin panel real-time chat page or through a messaging bot, no reply arrives for an extended period, or a “request timed out” error is displayed.

Likely Causes

  • The LLM service has not been configured, or the configuration is incorrect

  • The API key is wrong or has expired

  • The device’s network connection is unstable

  • The LLM provider’s API is temporarily unavailable

Resolution Steps

  1. Review the LLM configuration

    Go to Web Admin Panel → LLM Configuration and confirm that all of the following fields are filled in correctly:

    • API Base URL (the provider endpoint)

    • API Key

    • Model ID

    • Authentication method (must match the provider’s requirements)

  2. Verify that the API key is valid

    Test the key from your computer using curl:

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

    A successful response lists available models. An HTTP 401 response means the key is invalid or expired.

  3. Confirm the device has network access

    Check the device Wi-Fi connection status from the serial terminal or review network request logs in the Web admin panel.

  4. Check the LLM provider status page

    Visit the provider’s official status page to confirm there are no ongoing incidents. If there is a provider-side outage, wait for it to be resolved.

  5. Check for network access restrictions

    In some regions or network environments, certain LLM provider endpoints may not be reachable directly. Confirm that the device’s network can access the target API address.

Garbled Replies or Wrong Language

Symptom

AI replies are in an unexpected language (for example, English when Chinese is expected), or the reply text contains garbled characters.

Likely Causes

  • No preferred reply language has been specified for the Agent

  • The USER.md file does not include a language preference

  • The model infers language from context

Resolution Steps

  1. Tell the Agent your language preference directly in the conversation

    The simplest approach is to instruct the Agent directly:

    Please always reply to me in English.

    The Agent will remember this preference and apply it for the rest of the conversation.

  2. Set a language preference in USER.md

    Go to Web Admin Panel → File Management and edit the USER.md file. Add a language preference near the top:

    # User Preferences
- Always reply in English.
- Technical terms may remain in their original language, but explanations should be in English.

    After saving, the Agent will load this file as context at the start of every new conversation.

  3. Investigate garbled characters

    If the issue is garbled text rather than a language mismatch, check the following:

    • Verify the Web admin panel page encoding is UTF-8 (view the page source in the browser to confirm)

    • Check whether the messaging platform (Telegram, WeChat, etc.) fully supports Unicode characters

“Model Not Found” or “Authentication Failed” Error

Symptom

AI conversations return errors such as model not found, invalid model, authentication failed, or unauthorized.

Likely Causes

  • The Model ID contains a typo (model IDs are case-sensitive)

  • A model name unsupported by the provider was entered

  • The authentication method does not match the provider’s requirements

  • The API key format is incorrect

Resolution Steps

  1. Verify the Model ID

    Model IDs are case-sensitive and the naming format varies by provider. Copy the exact Model ID from the provider’s official documentation. For reference:

    Provider

    Example Model IDs

    Anthropic

    claude-opus-4-5, claude-sonnet-4-5

    OpenAI

    gpt-4o, gpt-4o-mini

    DeepSeek

    deepseek-chat, deepseek-reasoner

  2. Check the authentication method

    Different providers use different authentication schemes:

    • Anthropic: Select the Anthropic authentication method in LLM Configuration, which uses the x-api-key header

    • OpenAI-compatible endpoints: Use the standard Bearer Token authentication method

    In Web Admin Panel → LLM Configuration, confirm that the selected authentication method matches the provider documentation.

  3. Check the API key format

    Make sure the key was copied in full with no leading or trailing spaces or newline characters. Provider key formats differ (for example, Anthropic keys start with sk-ant-, while OpenAI keys start with sk-).

  4. Test API connectivity from your computer

    Use the sample curl command from the provider’s documentation to test whether the key works, independently of the device.

Replies Are Truncated or Incomplete

Symptom

AI replies are visibly cut off mid-sentence, or long responses stop after only the first portion.

Likely Causes

  • The maximum token limit is set too low

  • The model has reached its maximum output length

Resolution Steps

  1. Increase the maximum token limit

    Go to Web Admin Panel → LLM Configuration → Advanced Settings and increase the “Max Tokens” value. A setting of 2048 or 4096 is recommended for most tasks; the upper bound depends on the model in use.

  2. Check the model’s maximum output length

    Consult the provider documentation for the max_output_tokens limit of the model you are using. Do not set Max Tokens above this value.

  3. Ask the Agent to continue in the conversation

    If a reply is already truncated, send “Please continue” and the Agent will resume from where it left off.

Tip

Increasing Max Tokens raises the cost of each API call. For typical tasks, 1024 to 2048 is usually sufficient. Only increase the value when you regularly need longer responses.

Lua Skill Issues

Skill Execution Error: “module not found”

Symptom

When the Agent executes a Lua Skill, the response includes an error such as module not found or module 'xxx' not found, and the Skill fails.

Likely Causes

  • The Skill is attempting to require a hardware module that is only available in REPL mode

  • Certain hardware modules (wifi, spi, uart, pwm, ir, lcdc, adc, thermal, touch, and others) are intentionally excluded from the Skill sandbox for security and resource management reasons

Resolution Steps

  1. Identify which modules the Skill is importing

    Review the Lua Skill code and check whether it calls require on any of the following restricted modules:

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

  2. Switch to Lua REPL mode

    For tasks that require hardware modules, use the Lua REPL mode via AT command instead:

    AT+CLAW=lua

    Once in REPL mode, you can require hardware modules and execute code interactively.

  3. Ask the Agent to use REPL mode

    Tell the Agent to change the execution method directly:

    Please re-run this Lua code using REPL mode instead.

    The Agent will switch to the appropriate execution method automatically.

Note

Skill mode is designed for stateless tasks that do not depend on low-level hardware access (such as data processing, HTTP requests, and format conversion). For hardware control tasks, use REPL mode or encapsulate the hardware access behind a dedicated Skill interface.

GPIO Control Has No Effect / Wrong Pin

Symptom

The Lua code executed by the Agent performs GPIO operations, but the physical hardware (LED, relay, etc.) does not respond, or the wrong component is being controlled.

Likely Causes

  • The GPIO number in the code does not correspond to the correct physical pin

  • The actual pin assignment of the development board has not been verified

  • The target pin may already be in use by another function

Resolution Steps

  1. Activate the board_hardware_info Skill to query pin information

    Tell the Agent in the conversation:

    Activate board_hardware_info to query available pins and their functions.

    The Agent will call this Skill to retrieve the pin mapping table for the current board, including the functions supported by each pin (GPIO / ADC / PWM / SPI / I2C, etc.).

  2. Correct the pin number based on the query result

    After obtaining the pin information, instruct the Agent:

    Which pin is the on-board LED connected to? Please rewrite the control code using the correct pin number.

  3. Verify pin direction and initial level

    Before controlling a GPIO pin, confirm that the code sets the correct pin direction (input or output) and initial logic level.

  4. Check for pin conflicts

    Some pins are reserved during system initialization for functions such as UART (serial logging) or SPI (Wi-Fi). Attempting to use these as general-purpose GPIO will have no effect. When querying pin information, look for pins marked “occupied” or “reserved”.

Skill Execution Times Out

Symptom

When the Agent executes a Lua Skill, the task is terminated with a timeout error before it completes. This typically occurs when the Skill contains delay loops, continuous monitoring logic, or long wait operations.

Likely Causes

  • lua_run mode enforces a 30-second timeout

  • The Skill code contains long sleep loops or blocking wait logic

Resolution Steps

  1. Understand the execution mode timeout limits

    • lua_run: synchronous execution with a maximum of 30 seconds; suitable for short, one-shot tasks

    • lua_run_async: asynchronous execution; suitable for long-running background tasks

  2. Ask the Agent to switch to async mode

    Describe the requirement in the conversation and ask the Agent to rewrite the Skill:

    This task needs to run continuously. Please rewrite the Skill as an async version using lua_run_async.

  3. Refactor long-running tasks to use event-driven patterns

    For periodic tasks, use a timer rather than a sleep loop to reduce resource usage:

    -- Recommended: use a timer
local timer = require("timer")
timer.create(1000, function()
    -- executes every 1000 ms
end)

-- Not recommended: sleep loop inside lua_run (will time out)
while true do
    do_something()
    os.sleep(1000)
end

Tip

Long-running background tasks (such as continuous sensor monitoring or persistent message pushing) should always use lua_run_async. Reserve lua_run for one-off, short-lived tasks.

IM Bot Issues

Telegram Bot Does Not Respond

Symptom

Messages sent to the Telegram bot receive no reply, either for an extended period after first setup or following a period of normal operation.

Likely Causes

  • The Bot Token is configured incorrectly or has been revoked

  • The /start command has not been sent to the bot (required for first use)

  • The device’s network connection is down

  • The Telegram API is not reachable from the current network environment

Resolution Steps

  1. Confirm the Bot Token is correct

    Go to Web Admin Panel → Messaging Bot Configuration → Telegram and verify that the Bot Token is complete and contains no extra spaces. A valid Bot Token follows the format 1234567890:AAXXXXXX... (digits, a colon, then an alphanumeric string).

  2. Send the /start command to the bot

    For first-time use, you must search for the bot by its username in Telegram, then tap “Start” or send the /start command to open the conversation. Due to Telegram’s security model, a bot cannot send messages to a user who has not initiated a conversation with it.

  3. Check the device’s network connection

    Review the serial logs to confirm that the device Wi-Fi is connected and that external network access is working.

  4. Verify Telegram API accessibility from the device’s network

    Some networks (corporate environments, or certain geographic regions) block access to the Telegram API (api.telegram.org). Test reachability from your computer:

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

    If this request fails, resolve the network access issue before proceeding.

  5. Resave the configuration and restart

    In the Web admin panel, resave the Telegram configuration, then restart the device (via the admin panel or by cycling power).

WeChat QR Code Scan Has No Effect

Symptom

After configuring the WeChat bot in the Web admin panel and scanning the displayed QR code with WeChat, the admin panel status remains “Not Connected” or “Waiting for Scan” with no change.

Likely Causes

  • The iLink URL is configured incorrectly

  • The QR code has expired or was not generated correctly

  • The configuration was not saved before scanning

  • The device is offline and cannot communicate with the iLink server

Resolution Steps

  1. Confirm the iLink URL is correct

    The WeChat bot connects through the iLink platform. Verify that the iLink URL entered in the admin panel is correct; it is typically:

    https://ilinkai.weixin.qq.com

    Make sure HTTPS is used, and that no trailing slash or extra path segment has been added.

  2. Save the configuration, then regenerate the QR code

    Click “Save” to commit the configuration first, then click “Regenerate QR Code” or refresh the page to get a fresh code before scanning.

  3. Wait a moment after scanning

    The status update can take 5 to 10 seconds after the scan. Wait patiently without refreshing the page.

  4. Restart the device and retry

    After saving the configuration, restart the device via the admin panel or by cycling power, wait for it to come back online, regenerate the QR code, and scan again:

    AT+CLAW=reboot

  5. Verify the device has network access

    The device must be able to reach the iLink server to complete the WeChat bot authentication flow. Confirm that the Wi-Fi connection is up and that external network access is working.

Factory Reset

When the device has a problem that cannot be resolved through normal troubleshooting, or you need to start fresh from a clean state, follow these steps to restore the device to its factory defaults.

Reset Scope and AT Commands

What Is Reset

AT Command

Notes

Wi-Fi configuration

AT+CLAW=wifi,clear

Device enters SoftAP hotspot mode on next boot

All conversation history

AT+CLAW=session,clear,all

Clears all Agent dialogue records

Long-term memory

AT+CLAW=memory,clear

Clears accumulated user preference memory

Complete Reset Procedure

  1. Send AT commands via serial (use as needed)

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

  2. Restore default system files via the Web admin panel

    Go to Web Admin Panel → File Management and locate any system files that have been modified (such as AGENTS.md, SOUL.md, USER.md, etc.). Click “Restore Default” to revert each file to its factory content.

  3. Re-flash the firmware (most thorough option)

    If the steps above do not resolve the issue, or if you need to upgrade to the latest firmware, use the online flash tool to write a complete firmware image. This will erase all user data.

Warning

A factory reset permanently and irrecoverably erases all of the following:

  • Wi-Fi connection configuration

  • LLM API keys and model configuration

  • All Agent conversation history

  • Agent accumulated long-term memory

  • Custom Skills and configuration files

Before proceeding, make sure you have recorded all important configuration details, especially API keys.

Getting Help

When this document cannot resolve your issue, the following resources provide additional support.

Review device logs in real time

Serial logs are the most direct way to diagnose any problem. Nearly every abnormal condition leaves a record in the log:

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

Copy any error messages you observe. Having the exact log output makes it much easier to describe the problem accurately in a community forum or issue report.

Ask the Agent directly

The AmebaClaw Agent has self-diagnostic capability. In Web Admin Panel → Real-time Chat, you can ask the Agent questions such as:

Are there any errors in the recent logs?
Why did the Wi-Fi connection fail?
Please check whether my LLM configuration is correct.

The Agent will read the system state and logs to provide a diagnostic assessment.

GitHub Issues

Submit a bug report or search for solutions to known problems at:

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

When opening an issue, include the following information:

  • Firmware version (visible in the Web admin panel or in the serial boot log)

  • A detailed description of the problem and steps to reproduce it

  • Relevant error messages from the serial log

  • Troubleshooting steps you have already attempted

Tip

Before opening a new issue, search the existing Issues list using relevant keywords. Another user may have encountered the same problem and already found a solution.