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

RT-Thread官方账号 2026-06-03 432

描述

摘要：本文将和大家一起在 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 你好你好！我是运行在 RuiChing RK3506 (RT-Thread) 上的 AI 助手... msh />/ai 把 GPIO160 设为高电平已设置 GPIO 160 为高电平（HIGH）。 msh />/ai 让 GPIO160 每 500ms 闪烁 GPIO 160 开始闪烁，间隔 500ms... msh />/ai 停止闪烁已停止所有闪烁。

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

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

开发板

4. 两种集成模式的选择

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

● 官方模式（框架优先）：RT-Claw 是 Git 根目录，各平台以 platform// 子目录存在，每个平台是一个完整工程，构建系统以 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 = cwd src = 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 #include #include static void cmd_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());} static void cmd_board_info(int argc, char **argv){ (void)argc; (void)argv; rt_kprintf("Board: RuiChing Pi (RC3506)\n"); rt_kprintf("SoC: Rockchip RK3506\n");} static void cmd_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"),}; /* 网络自动配置线程 */static void board_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);} void board_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 */void claw_lcd_status(const char *msg) { (void)msg; }void claw_lcd_progress(int percent) { (void)percent; } const shell_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 #include "osal/claw_os.h"#include "claw/claw_init.h"#include "claw_board.h" int main(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 #include #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 #include int claw_net_http_post(const char *url, const char *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 static const int s_gpio_policy[] = { 0,1,2,3,...,40,160 }; static int gpio_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;} int tool_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。如果在移植过程中遇到了本文没提到的问题，欢迎在评论区交流讨论。

打开APP阅读更多精彩内容