AT Commands

Overview

Ameba-Claw exposes its full feature set through a compact AT command interface over the serial port. Every operation — chatting with the agent, configuring the LLM backend, managing memory, running Lua skills, and browsing the virtual filesystem — is reachable with a single AT+CLAW=... command.

All commands follow the same prefix: AT+CLAW=<action>[,<arguments>]

If the board is not yet configured, start with the Wi-Fi and LLM configuration commands before sending any ask commands.

Connecting to Serial

Connect to the board’s primary UART port with any serial terminal (PuTTY, minicom, screen, or the Arduino IDE serial monitor).

Default settings:

Parameter	Value
Baud rate	115200
Data bits	8
Parity	None
Stop bits	1
Flow control	None

After the board boots you will see a shell prompt. Type AT commands directly into the terminal and press Enter to send each one.

Tip

If you see garbled output on boot, check that your terminal baud rate matches 115200.

Command Reference

Chat

Command

Description

AT+CLAW=ask,<message>

Send a message to the agent and receive a reply. <message> is plain text — no quotes

required unless the message itself contains a comma.

Example

AT+CLAW=ask,What is the current temperature on the board?

LLM Configuration

Use AT+CLAW=cfg to inspect or update the LLM backend settings. Changes are persisted to flash and take effect immediately.

Command	Description
`AT+CLAW=cfg`	Print the current LLM configuration (model, URL, backend type). The API key is shown masked for security.
`AT+CLAW=cfg,key,<val>`	Set the API key used to authenticate requests to the LLM provider.
`AT+CLAW=cfg,model,<val>`	Set the model identifier (e.g. `gpt-4o`, `claude-3-5-sonnet-20241022`, `qwen-turbo`, `deepseek-chat`).
`AT+CLAW=cfg,url,<val>`	Set the API endpoint URL. Use this to point the agent at a custom or OpenAI-compatible endpoint.
`AT+CLAW=cfg,backend,<0\|2>`	Set the authentication scheme. `0` = Bearer token (OpenAI and compatible providers). `2` = Anthropic (`x-api-key` header). Match this to your LLM provider.

Examples

AT+CLAW=cfg
AT+CLAW=cfg,key,sk-xxxxxxxxxxxxxxxxxxxxxxxx
AT+CLAW=cfg,model,gpt-4o
AT+CLAW=cfg,url,https://api.openai.com/v1/chat/completions
AT+CLAW=cfg,backend,0

Note

For Anthropic (Claude) models, set backend to 2 and use your Anthropic API key. For OpenAI, Qwen, DeepSeek, or any OpenAI-compatible provider, use backend 0.

Wi-Fi

Command

Description

AT+WLCONN=ssid,<ssid>,pw,<pass>

Connect to a Wi-Fi network (low-level command). Takes effect immediately and

saves credentials persistently.

AT+CLAW=cfg,wifi,<ssid>,<pass>

Connect to a Wi-Fi network (application-level command). Same behavior as

AT+WLCONN.

AT+CLAW=wifi,clear

Erase saved Wi-Fi credentials and reboot the board into SoftAP mode. Use this to

reconfigure the network from scratch.

Examples

AT+WLCONN=ssid,MyNetwork,pw,MyPassword
AT+CLAW=cfg,wifi,MyNetwork,MyPassword
AT+CLAW=wifi,clear

Memory Management

Long-term memory is stored in vfs:/MEMORY.md. The agent reads this file at the start of each session to recall facts about the user and previous interactions.

Command	Description
`AT+CLAW=memory,list`	Display the current contents of long-term memory.
`AT+CLAW=memory,clear`	Erase all long-term memory.

Examples

AT+CLAW=memory,list
AT+CLAW=memory,clear

Session History

Each conversation session is stored as a .jsonl file under vfs:/session/. Sessions let the agent maintain context within a conversation; they do not persist across reboots unless explicitly saved.

Command	Description
`AT+CLAW=session,list`	List all saved session files.
`AT+CLAW=session,clear`	Clear the current active session.
`AT+CLAW=session,clear,all`	Delete all saved session files.

Examples

AT+CLAW=session,list
AT+CLAW=session,clear
AT+CLAW=session,clear,all

Skills

Lua skills are self-contained scripts that extend what the agent can do without recompiling firmware. The agent can invoke skills automatically, or you can trigger them directly from the serial terminal.

Command	Description
`AT+CLAW=skill,<name>`	Run a script-type Skill directly. Knowledge-type Skills (no script) are not executable this way — activate them through conversation instead.
`AT+CLAW=skill,<name>,<json_args>`	Run a script-type Skill and pass a JSON object as the `args` table to `run()`.
`AT+CLAW=cap`	List all registered C-layer Capabilities (not the Skill list).
`AT+CLAW=cap,skill_list`	List all installed Skills (calls the `skill_list` Capability).

Examples

AT+CLAW=cap
AT+CLAW=cap,skill_list
AT+CLAW=skill,usb_file
AT+CLAW=skill,blink_led,{"pin":"PA_22","times":10}

Note

AT+CLAW=cap lists registered Capabilities (C-layer tools such as lua_run, file_read, skill_list). To see installed Skills, use AT+CLAW=cap,skill_list.

Filesystem

Ameba-Claw uses a virtual filesystem (VFS) to store configuration files, skills, session history, and user data. The fs command lets you inspect and manage these files from the serial terminal.

Command	Description
`AT+CLAW=fs,list,<path>`	List the contents of `<path>` in the VFS.
`AT+CLAW=fs,delete,<path>`	Delete the file at `<path>`.

Examples

AT+CLAW=fs,list,/
AT+CLAW=fs,list,/skills
AT+CLAW=fs,delete,/tmp/test.lua

Warning

Deleting system files such as /AGENTS.md or /SOUL.md will remove the agent’s persona and role definition. The agent will revert to default behavior until these files are restored.

Key VFS paths

Path	Purpose
`vfs:/AGENTS.md`	System prompt and agent role definition
`vfs:/SOUL.md`	Agent personality
`vfs:/IDENTITY.md`	Agent identity
`vfs:/USER.md`	User information — name, preferences, preferred language
`vfs:/MEMORY.md`	Long-term memory
`vfs:/session/<id>.jsonl`	Per-session conversation history
`vfs:/skills/<name>/`	Installed Lua skill packages
`vfs:/scheduler/`	Scheduled job definitions
`vfs:/mcp/`	MCP server configurations

Lua REPL Mode

The Lua REPL (Read-Eval-Print Loop) lets you run Lua code interactively over serial. It is useful for testing hardware access, exploring the available Lua modules, and prototyping skill scripts before saving them to the filesystem.

Entering the REPL

AT+CLAW=lua

After sending this command the terminal switches into Lua mode. You will see a > prompt. Type any Lua expression or statement and press Enter to execute it.

> print("Hello from Ameba-Claw!")
Hello from Ameba-Claw!
> 1 + 2
3
> sys.millis()
42317
> sys.uptime()
42.317

To exit the REPL and return to AT command mode, type exit or press Ctrl+C.

Available Lua Modules

The following modules are available inside skill scripts as well as in the REPL:

Software modules

Module	Description
`cap`	Call registered capabilities (skills). Returns two values: `ok` (boolean) and `result_json` (string).
`file`	Read, write, and manage files on the VFS.
`sys`	System utilities: `sys.millis()` monotonic ms since boot, `sys.uptime()` seconds since boot (float), `sys.sleep_ms(n)` blocking sleep. No Unix timestamp function.
`cjson`	JSON encode and decode.
`timer`	One-shot and repeating timers.
`udp`	UDP socket communication.
`event`	Inter-task event signaling.

Hardware modules

Module	Description
`gpio`	Digital I/O; `gpio.on(pin, edge, fn)` for interrupt-driven callbacks.
`button`	Event-driven button detection (press/release callbacks), wrapper over `gpio`.
`i2c`	I2C master communication.
`spi`	SPI master byte-level read/write.
`rtc`	Real-time clock read and set.
`display`	Unified display output API for SPI and LCDC screens.
`audio`	Audio capture and playback.
`usb_msc`	USB Mass Storage (FAT32 drive) access.
`usb_uvc`	USB Video Class (camera) access.

REPL-only modules (not available inside Skill scripts)

Module	Description
`wifi`	Wi-Fi station and SoftAP control.
`uart`	UART configuration and communication.
`pwm`	PWM output control.
`ir`	Infrared transmit and receive.
`lcdc`	LCD controller.
`adc`	Analog-to-digital conversion.
`thermal`	On-chip temperature sensor.
`touch`	Capacitive touch input.
`basictimer`	Hardware basic timer for precision timing.
`led_strip`	WS2812 programmable LED strip control.

Warning

REPL-only modules (wifi, uart, pwm, ir, lcdc, adc, thermal, touch, basictimer, led_strip) are not available inside Skill scripts. Use them only for interactive REPL sessions. spi, display, button, gpio, i2c, rtc, and audio are available in both environments.

Writing Skill Scripts

Every Lua skill script must define a run function as its entry point:

function run(args)
    -- args is already a decoded Lua table — do NOT call cjson.decode(args)
    local pin = args.pin or "PA_22"
    return '{"status":"ok"}'
end

Scripts are stored at the following paths depending on their purpose:

Path	Purpose
`vfs:/tmp/<name>.lua`	Throwaway scripts — erased on reboot
`vfs:/scripts/<name>.lua`	Persistent user applications
`vfs:/skills/<name>/scripts/main.lua`	LLM-invokable skills — the agent can call these by name

Calling another capability from a skill

cap.call returns two values. Always capture both:

function run(args)
    local ok, result_json = cap.call("board_hardware_info", "")
    if not ok then
        return "Error: " .. result_json
    end
    local info = cjson.decode(result_json)
    return cjson.encode(info)
end

Lua version notes

The runtime is Lua 5.4. Use the native bitwise operators &, |, ~, >>, << instead of the bit module (which is not loaded). The os module is not available; use sys instead:

local t = sys.time()       -- Unix timestamp (integer)
sys.sleep_ms(500)          -- Sleep 500 ms

Tip

Activate the builtin_lua_modules built-in skill (AT+CLAW=skill,builtin_lua_modules) to load a full index of all Lua module APIs. This gives the agent the reference it needs to write correct skill scripts on your behalf.

Activate board_hardware_info before asking the agent to write any hardware-related script, so it knows which pins and peripherals are available on your specific board.