手把手教你把 RT-Claw AI 助手移植到睿擎 RK3506 开发板

摘要：本文将和大家一起在 RT-Thread 睿擎 RK3506 平台上「跑起来」一个 AI Agent——RT-Claw。按照本文的步骤，你很快就能在开发板上实现「对着串口和 AI 聊天，让 AI 帮你控制 GPIO」的功能。我们会一步一步演示完整的移植过程，包括构建系统桥接、Shell 命令注册、HTTPS 网络层重写、GPIO 工具适配等关键环节。文章最后还会分享几个移植过程中踩过的坑，帮你少走冤枉路。

1. 前言：为什么要在嵌入式板子上跑 AI Agent？

最近 AI Agent 的概念火得不行，但在 PC 上跑和在一个只有 128MB 内存的嵌入式板子上跑，完全是两码事。RT-Claw 是一个专门为嵌入式设备设计的实时 AI Agent 框架，它支持多轮对话、工具调用（Tool Use）、定时调度等功能，最吸引人的是：你可以用自然语言让 AI 帮你控制硬件——比如对着串口说一句"把 LED 打开"，AI 就会自动调用 GPIO 工具帮你点灯。

RK3506 是 Rockchip 面向工业边缘计算推出的四核异构 SoC（3× Cortex-A7 + 1× Cortex-M0），睿擎（RuiChing）平台为它提供了完整的 RT-Thread 5.x SMP BSP。把 RT-Claw 移植到 RK3506，本质上是在一个已有完整 BSP 的 RT-Thread 工程中，以最小侵入的方式集成 RT-Claw，让它能利用 RT-Thread 的 OSAL 和网络协议栈，完成「自然语言 → AI 理解 → 工具调用 → 硬件操作」的完整闭环。

本文基于笔者实际移植过程编写，软硬件环境如下：

2. 开发准备

在开始移植之前，请确保你已准备好以下环境和材料：

1）RuiChing Pi（RC3506）开发板一块。如果你还没有，可以在睿擎官方渠道购买。

2）RuiChing Studio 开发环境。安装步骤简述如下（详细说明请参考睿擎官方文档）：

●安装 RuiChing Studio（基于 Eclipse 的 IDE）

●安装 arm-none-eabi-gcc 工具链（Studio 一般会自带）

●准备一根 USB 转串口线，用于连接开发板的 UART0（波特率 115200 8N1）

3）RT-Claw 源码。从官方仓库克隆：

git clone https://gitee.com/zevorn/rt-claw.git

4）一张可用的 AI API 密钥。本文以 DeepSeek 为例，你也可以使用 OpenAI、Moonshot 等其他兼容 OpenAI 接口格式的服务。

小提示：如果你是第一次接触 RT-Claw，建议先读完本文的「效果预览」章节，看看最终能做出什么效果，这样在后面遇到繁琐的配置步骤时，会更有动力坚持下去。

3. 效果预览

在开始动手之前，让我们先看看最终效果。烧录固件、上电后，串口终端会打印如下启动信息：

========================================  RT-Claw on RuiChing RK3506  Rockchip RK3506 @ 1.5GHz (3x A7)========================================[Board] RuiChing RK3506 early init done.[Board] e1 configured[CLAW] Gateway initialized[CLAW] Network service initialized[CLAW] AI engine initialized - 8 tools registeredmsh />

看到 msh /> 提示符后，我们就可以和 AI 对话了：

msh />/ai 你好<rt-claw> 你好！我是运行在 RuiChing RK3506 (RT-Thread) 上的 AI 助手...msh />/ai 把 GPIO160 设为高电平<rt-claw> 已设置 GPIO 160 为高电平（HIGH）。msh />/ai 让 GPIO160 每 500ms 闪烁<rt-claw> GPIO 160 开始闪烁，间隔 500ms...msh />/ai 停止闪烁<rt-claw> 已停止所有闪烁。

Cool！AI 能正确理解你的自然语言指令，自动调用 gpio_set、gpio_blink、gpio_blink_stop 等工具，并在接收到工具返回结果后继续生成自然语言回复。这就是我们想要的效果：对着串口说话，AI 帮你控制硬件。

当然，除了 AI 对话，还有一系列板级命令可以直接使用：

4. 两种集成模式的选择

在正式动手之前，我们需要做一个重要的架构决策：RT-Claw 官方仓库采用的是「框架优先」模式，而我们要做的是「BSP 优先」模式。两者的对比如下（完整框图见 drawio/architecture-comparison.drawio）：

●官方模式（框架优先）：RT-Claw 是 Git 根目录，各平台以 platform/<name>/ 子目录存在，每个平台是一个完整工程，构建系统以 Meson 为元构建。

●用户模式（BSP 优先）：RuiChing BSP 是 Git 根目录，RT-Claw 被放在 packages/rt-claw/ 下，完全复用 BSP 已有的纯 SCons 构建体系。

为什么选 BSP 优先模式？原因很简单：RuiChing BSP 已经有完整的工具链、调试配置和外设驱动，我们不想「重新造一个 BSP」。而且现代 AI API 都要求 HTTPS，官方代码只支持 HTTP，网络层必须重写——既然总要改代码，那就不如选择更省事的集成方式。

整个移植流程可以分为四个阶段：

下面我们一步一步来实现。

5. Phase 1：把 RT-Claw 放进工程

5.1 放入源码

首先，在你的 RuiChing BSP 工程根目录下创建 packages/rt-claw/，然后把 RT-Claw 的源码复制进去。复制完成后，目录结构大概是这样的：

RT_CLAW_demo/├── applications/│   └── main.c├── board/├── packages/│   └── rt-claw/│       ├── claw/          ← 核心框架代码│       ├── osal/│       │   └── rtthread/  ← RT-Thread OSAL（这个直接复用）│       ├── include/       ← 公共头文件│       └── vendor/        ← 第三方库（后面要处理冲突）├── rt-thread/└── ...

注意：osal/freertos/ 这个目录对 RT-Thread 平台没用，可以直接删掉，避免编译器搜索路径干扰。

5.2 编写 SConscript

RT-Thread 的构建系统通过递归遍历 packages/ 下各子目录的 SConscript 文件来实现组件自动发现。所以我们需要在 packages/rt-claw/ 下新建一个 SConscript：

# packages/rt-claw/SConscriptimport osfrom building import *Import('RTT_ROOT')Import('rtconfig')PKGNAME = 'rt-claw'DEPENDS = []cwd = GetCurrentDir()root = cwdsrc = Split('''    claw/claw_init.c    claw/core/gateway.c    claw/core/scheduler.c    claw/services/ai/ai_engine.c    claw/services/ai/ai_memory.c    claw/services/ai/ai_skill.c    claw/services/im/feishu.c    claw/services/net/net_service.c    claw/services/swarm/swarm.c    claw/shell/shell_commands.c    claw/tools/claw_tools.c    claw/tools/tool_gpio.c    claw/tools/tool_sched.c    claw/tools/tool_system.c    claw/tools/tool_net.c    osal/rtthread/claw_os_rtthread.c    osal/rtthread/claw_net_rtthread.c    osal/rtthread/claw_shell_msh.c''')CPPPATH = [    os.path.join(root, 'include'),    os.path.join(root, '.'),    os.path.join(root, 'include', 'claw'),]# 复用 RT-Thread 系统的 cJSONcjson_path = os.path.join(RTT_ROOT, 'components', 'data_parsers', 'cJSON')if os.path.exists(cjson_path):    CPPPATH.append(cjson_path)CPPDEFINES = [    'CLAW_PLATFORM_RTTHREAD',    'CLAW_HAS_GENERATED_CONFIG',    'CONFIG_RTCLAW_SKILL_ENABLE',    'CONFIG_RTCLAW_TOOL_GPIO',    'CONFIG_RTCLAW_TOOL_SYSTEM',    'CONFIG_RTCLAW_TOOL_SCHED',    'CONFIG_RTCLAW_TOOL_NET',    'CONFIG_RTCLAW_AI_BOOT_TEST',]objs = DefineGroup(name=PKGNAME, src=src, depend=DEPENDS,                   CPPPATH=CPPPATH, CPPDEFINES=CPPDEFINES)Return("objs")

这里有几个关键点需要大家注意：

●CPPPATH 中加入了 packages/rt-claw/include/，这样源码里的 #include "osal/claw_os.h" 才能找到对应的文件。

●CPPDEFINES 中的宏既是「平台标识」也是「功能开关」，相当于替代了官方 Meson 构建的 meson_options.txt。

5.3 创建 claw_gen_config.h

官方 RT-Claw 靠 Meson 自动生成 claw_config.h，但我们的工程里没有 Meson，所以需要手动创建一个：

/* packages/rt-claw/include/claw_gen_config.h */#ifndef CLAW_GEN_CONFIG_H#define CLAW_GEN_CONFIG_H/* AI 配置 — 实际值在 board_rtclaw.c 里运行时注入 *//* #define CONFIG_RTCLAW_AI_API_URL  "https://api.deepseek.com/v1/chat/completions" *//* #define CONFIG_RTCLAW_AI_MODEL    "deepseek-chat" */#endif

这个文件目前可以留空，主要作用是配合 CLAW_HAS_GENERATED_CONFIG 宏，告诉 RT-Claw「配置已经生成好了」。

6. Phase 2：板级适配

6.1 创建 board_rtclaw.c

RT-Claw 通过 claw_board.h 定义了框架和板级硬件之间的接口契约。我们需要在 board/ 目录下实现这些接口：

/* board/board_rtclaw.c */#include"claw_board.h"#include"claw_config.h"#include<rtthread.h>#include<rtdevice.h>#include<msh.h>staticvoidcmd_info(int argc, char **argv){    (void)argc; (void)argv;    rt_kprintf("Project: rt-claw\n");    rt_kprintf("Version: %s\n", RT_CLAW_VERSION);    rt_kprintf("Platform: RuiChing RK3506\n");    rt_kprintf("Uptime: %lu ticks\n", rt_tick_get());}staticvoidcmd_board_info(int argc, char **argv){    (void)argc; (void)argv;    rt_kprintf("Board: RuiChing Pi (RC3506)\n");    rt_kprintf("SoC: Rockchip RK3506\n");}staticvoidcmd_reboot(int argc, char **argv){    (void)argc; (void)argv;    rt_hw_cpu_reset();}static const shell_cmd_t s_ruiching_cmds[] = {    SHELL_CMD("/info",       cmd_info,       "Show system info"),    SHELL_CMD("/board_info", cmd_board_info, "Show board info"),    SHELL_CMD("/reboot",     cmd_reboot,     "Reboot"),};/* 网络自动配置线程 */staticvoidboard_net_config_thread(void *arg){    (void)arg;    rt_thread_mdelay(3000);  /* 等网卡就绪 */    msh_exec("ifconfig e1 10.23.8.66 10.23.8.254 255.255.255.0", 50);}voidboard_early_init(void){    rt_thread_t tid = rt_thread_create("net_cfg",                                        board_net_config_thread,                                        RT_NULL, 1024,                                        RT_THREAD_PRIORITY_MAX - 1, 10);    if (tid) rt_thread_startup(tid);    /* 注入 AI 配置 */    ai_set_api_url("https://api.deepseek.com/v1/chat/completions");    ai_set_model("deepseek-chat");    ai_set_api_key("sk-xxxxxxxx");}/* LCD stub — 暂时没有 LCD */voidclaw_lcd_status(constchar *msg){ (void)msg; }voidclaw_lcd_progress(int percent){ (void)percent; }constshell_cmd_t *board_platform_commands(int *count){    *count = sizeof(s_ruiching_cmds) / sizeof(s_ruiching_cmds[0]);    return s_ruiching_cmds;}

这里我们做了三件事：一是注册了三个板级命令（/info、/board_info、/reboot）；二是创建了一个后台线程来自动配置网卡 IP；三是注入了 AI 后端地址和 API Key。claw_lcd_* 暂时做空实现，等后面接了屏再填内容。

6.2 修改 main.c

最后，修改 applications/main.c，在启动时调用 claw_init()：

#include<rtthread.h>#include"osal/claw_os.h"#include"claw/claw_init.h"#include"claw_board.h"intmain(void){    rt_kprintf("\n========================================\n");    rt_kprintf("  RT-Claw on RuiChing RK3506\n");    rt_kprintf("========================================\n\n");    claw_log_set_enabled(1);    board_early_init();    claw_init();    return 0;}

到这里，如果你现在编译，大概率会报一堆错——因为我们还没处理代码冲突和 Shell 命令注册。别急，Phase 3 就是来解决这些问题的。

7. Phase 3：平台适配（重点）

7.1 删掉冲突的 cJSON

RT-Claw 自带了一份 vendor/lib/cjson/cJSON.c，但 RT-Thread 系统里已经有 cJSON 了。两份同时参与链接会导致「Multiple Definition」错误。处理办法很简单：

rm packages/rt-claw/vendor/lib/cjson/cJSON.c

小贴士：RT-Thread 的 cJSON 和 RT-Claw 自带的版本在核心 API（cJSON_CreateObject、cJSON_Parse、cJSON_Print 等）上是兼容的，所以放心删。

7.2 Shell 命令桥接（核心难点）

这是整个移植过程中最绕的一个环节。RT-Claw 的命令以 / 开头，比如 /log、/ai、/skill。但 RT-Thread 的 MSH_CMD_EXPORT_ALIAS 宏会把 alias 拼接到 C 标识符里：MSH_CMD_EXPORT_ALIAS(cmd, /log, "desc") 会展开成 __fsym_/log_name，而 / 不是合法 C 标识符字符，直接编译报错。

解决办法：绕过宏，直接构造 finsh_syscall 结构体，放到 FSymTab 段里。

/* packages/rt-claw/osal/rtthread/claw_shell_msh.c */#include<rtthread.h>#include<finsh.h>#include"claw/shell/shell_commands.h"#include"claw_board.h"static int claw_msh_dispatch(int argc, char **argv){    if (argc < 1) return -1;    if (shell_dispatch(shell_common_commands,                       shell_common_command_count(), argc, argv))        return 0;    int bcount = 0;    const shell_cmd_t *bcmds = board_platform_commands(&bcount);    if (bcount > 0 && shell_dispatch(bcmds, bcount, argc, argv))        return 0;    return -1;}#define CLAW_MSH_EXPORT(id, name_str, desc_str)                            \    const char __fsym_##id##_name[] rt_section(".rodata.name") = name_str; \    const char __fsym_##id##_desc[] rt_section(".rodata.name") = desc_str; \    rt_used const struct finsh_syscall __fsym_##id                          \        rt_section("FSymTab") = {                                           \            __fsym_##id##_name, __fsym_##id##_desc, 0,                      \            (syscall_func)&claw_msh_dispatch                                \        };CLAW_MSH_EXPORT(claw_log,      "/log",      "Toggle log")CLAW_MSH_EXPORT(claw_ai,       "/ai",       "Chat with AI")CLAW_MSH_EXPORT(claw_ai_set,   "/ai_set",   "Set AI config")CLAW_MSH_EXPORT(claw_skill,    "/skill",    "Execute skill")CLAW_MSH_EXPORT(claw_remember, "/remember", "Save memory")CLAW_MSH_EXPORT(claw_info,     "/info",     "System info")CLAW_MSH_EXPORT(claw_reboot,   "/reboot",   "Reboot")

这里的关键是 rt_used属性。没有它，链接器会把这些符号当成「未使用」优化掉，导致 msh 里一个 RT-Claw 命令都找不到。笔者在这里踩了半小时的坑才定位到问题，大家务必注意！

7.3 重写网络层：从 HTTP 升级到 HTTPS

官方 claw_net_rtthread.c 只支持 HTTP（还硬编码了端口 80），注释里写着「For HTTPS use an HTTP proxy」。但 DeepSeek、OpenAI 这些现代 AI API 全部强制 HTTPS，所以网络层必须重写。

我们改用 RT-Thread 官方的 webclient + mbedtls：

#include<rtthread.h>#include<webclient.h>intclaw_net_http_post(constchar *url, constchar *post_data,                       char *response, size_t response_size){    struct webclient_session *session = webclient_session_create(2048);    if (!session) return -1;    /* 注意：header 字符串必须显式包含 \r\n！ */    webclient_header_fields_add(session,        "Content-Type: application/json\r\n");    webclient_header_fields_add(session,        "Authorization: Bearer %s\r\n", ai_get_api_key());    webclient_header_fields_add(session,        "Content-Length: %d\r\n", (int)strlen(post_data));    if (webclient_post(session, url, post_data) < 0) {        webclient_close(session);        return -1;    }    int bytes = webclient_read(session, response, response_size - 1);    if (bytes > 0) response[bytes] = '\0';    webclient_close(session);    return bytes;}

这里有两个大坑，笔者都踩过：

1. webclient_header_fields_add() 不会自动追加\r\n。如果你忘了写，服务器会返回 400 Bad Request，调试时很难一眼看出来。

2. webclient_post() 不会自动计算 Content-Length。大多数 REST API 都要求这个头，少了它会报 411 Length Required 或者直接截断请求体。

另外，当前 mbedtls 的证书验证被临时设成了 MBEDTLS_SSL_VERIFY_NONE（开发调试用），正式上线前记得改回 VERIFY_REQUIRED 并配置 CA 证书。

7.4 GPIO 工具适配

RT-Claw 的 GPIO 工具原本只有 ESP-IDF 分支。我们需要给 RT-Thread 加一个：

#ifdef CLAW_PLATFORM_RTTHREAD#include<rtdevice.h>static const int s_gpio_policy[] = { 0,1,2,3,...,40,160 };staticintgpio_is_allowed(int pin){    for (int i = 0; i < sizeof(s_gpio_policy)/sizeof(s_gpio_policy[0]); i++)        if (s_gpio_policy[i] == pin) return 1;    return 0;}inttool_gpio_set(int pin, int value){    if (!gpio_is_allowed(pin)) return -1;    rt_pin_mode(pin, PIN_MODE_OUTPUT);    rt_pin_write(pin, value ? PIN_HIGH : PIN_LOW);    return 0;}#endif

特别强调 GPIO 白名单。因为 AI 会自动调用工具，如果没有限制，AI 可能误触连接到电源管理或复位信号的引脚，后果很严重。白名单就是一道安全闸。

另外，gpio_blink 最初用定时器回调实现，结果在回调里调了 rt_mutex_take，直接触发断言（ISR 里不能拿 mutex）。后来改成了专用线程才解决。如果你也打算做闪烁功能，建议直接用线程，别走定时器回调。

8. 编译、烧录与验证

做完以上步骤，我们就可以编译了。在工程根目录执行：

scons -j8

如果编译通过，用 RuiChing Studio 或 rkdeveloptool 把生成的固件烧到开发板。上电后，你应该能看到本章开头「最终效果预览」里的启动日志。

验证清单：

如果 /ai 命令没有返回，先检查网络：

msh />ping api.deepseek.com

ping 不通的话，检查 board_rtclaw.c 里的 IP 配置是否正确，或者确认你的网关能不能访问外网。

9. 踩坑记录与经验分享

移植过程中笔者踩了不少坑，这里整理出来，希望能帮你少走弯路。

坑 1：IDE 里满屏红线，但 scons 编译却通过了

现象：Eclipse 里显示大量「Unresolved inclusion」错误。

原因：RuiChing Studio 的索引器使用 .cproject 中的配置解析代码，而实际编译由 SCons 控制。如果只在 SConscript 里加了宏和头文件路径，没同步到 .cproject，就会出现这种「编译过、IDE 报错」的怪现象。

解决：在 Eclipse 的 C Compiler → Include paths 和 Defined symbols 中，手动添加 packages/rt-claw/include/ 路径和 CLAW_PLATFORM_RTTHREAD 等宏。

坑 2：RT-Claw 命令在 msh 里「消失」了

现象：烧录后输入 /info，提示 unknown command。

原因：claw_shell_msh.c 里的 __fsym_* 符号被链接器优化掉了。

解决：确保每个 finsh_syscall 变量都加了 rt_used 属性。

坑 3：HTTPS 请求返回 400 或 411

现象：AI 请求失败，网络层返回错误码。

原因：webclient_header_fields_add() 不会自动加 \r\n，且 webclient_post() 不会自动计算 Content-Length。

解决：每个 header 字符串手动加 \r\n，并显式传入 Content-Length。

坑 4：gpio_blink 触发 HardFault

现象：执行闪烁后系统崩溃，报错 _rt_mutex_take shall not be used in ISR。

原因：定时器回调里调用了涉及 mutex 的 OSAL 函数。

解决：改用专用线程实现闪烁逻辑。

10. 进阶玩法

完成基础移植后，你还可以尝试以下扩展：

持久化配置：把 API Key 和模型名写入 Flash 分区，避免每次烧录都硬编码。
恢复证书验证：把 mbedtls 从 VERIFY_NONE 改回 VERIFY_REQUIRED，并烧录 CA 根证书。
扩展 GPIO 白名单：根据实际硬件原理图，把 LED、按键、继电器等引脚加入白名单。
添加更多工具：比如 PWM 调光、ADC 读取、I2C/SPI 传感器访问。
开启 Swarm 和 Sched：等 BSP 修复 USB Host 驱动后，重新启用这两个功能模块。

11. 总结

本文和大家一起，一步一步完成了 RT-Claw AI Agent 框架在 RT-Thread 睿擎 RK3506 平台上的移植。整个过程最核心的挑战不是硬件适配，而是两个工程组织范式之间的桥接——把 Meson 管理的「框架优先」项目，以最小侵入的方式集成到 SCons 管理的「BSP 优先」工程中。

回顾一下，我们一共做了六件事：写 SConscript 桥接构建系统、创建 claw_gen_config.h 弥合配置差异、实现 board_rtclaw.c 完成板级对接、手写 FSymTab 条目解决 / 命令注册问题、用 webclient+mbedtls 重写 HTTPS 网络层、给 GPIO 工具加上 RT-Thread Pin 设备分支和白名单机制。

如果你按照本文的步骤操作，应该很快就能在 RK3506 上拥有一个「能听懂自然语言、会控制硬件」的 AI Agent。如果在移植过程中遇到了本文没提到的问题，欢迎在评论区交流讨论。

参考资源

●RT-Claw 官方仓库：https://gitee.com/zevorn/rt-claw

●睿擎 RK3506 文档：https://www.rt-thread.com/ruiching/document/site/

●RT-Thread 官方论坛：https://club.rt-thread.org

📺 下期直播预告

这篇文章讲的是 RT-Claw 在睿擎 RK3506 上的移植，文字版已经把关键步骤和踩坑点都梳理出来了。但如果你：

想看一遍完整的现场操作，从源码拉取到最终对话跑通
想了解 RT-Claw 的工具调用机制是怎么实现的
在实际移植中卡住了，想直接提问

欢迎来下期睿擎直播间，我们会现场演示完整流程，并解答大家在移植中遇到的问题。

⏰ 时间：6月10日（周三）20:00

🎯 主题：RT-Claw AI 助手移植实战——在睿擎 RK3506 上跑通「自然语言控制硬件」

📌 包含内容：

源码拉取 → 工程集成 → 编译烧录完整演示
Shell 命令桥接、HTTPS 网络层重写等关键环节现场操作
直播间专属福利：50元开发板优惠券 + 配套源码资料包

🔗 预约方式：点击下方链接获取预约链接和开播提醒。

下周三晚8点，直播间见

欢迎加入睿擎工业平台交流群

获取配套资料包