Linux 上使用 CLion 开发嵌入式，并用 Codex CLI-开发者社区

Linux 上使用 CLion 开发嵌入式，并用 Codex CLI 协作

适合对象：已经或准备使用 Ubuntu / Debian / Fedora 等 Linux 系统开发 STM32 的新手。

本教程目标：

Linux 安装嵌入式工具链 | v CLion 打开 STM32 CMake 工程 | v OpenOCD + GDB 下载调试 | v Codex CLI 在终端中辅助读代码、改代码、查错

官方资料入口：

CLion Embedded Development：https://www.jetbrains.com/help/clion/embedded-overview.html
CLion STM32CubeMX Projects：https://www.jetbrains.com/help/clion/embedded-stm32.html
CLion OpenOCD Support：https://www.jetbrains.com/help/clion/openocd-support.html
OpenAI Codex CLI：https://developers.openai.com/codex/cli
OpenAI Codex IDE Extension：https://developers.openai.com/codex/ide
Codex 开源仓库：https://github.com/openai/codex

1. 为什么很多嵌入式工程师喜欢 Linux

Linux 的优点：

命令行工具好用。
CMake、Make、Ninja、GCC、GDB、OpenOCD 安装方便。
适合自动化构建。
适合 Git 工作流。
适合和 Codex CLI 这类终端 AI 工具配合。

Linux 的缺点：

Keil5 原生不支持 Linux。
某些厂商烧录工具 Linux 支持不如 Windows。
USB 权限需要配置。
新手一开始会被命令行吓到。

如果你主要学习 STM32，推荐：

Linux + CLion + STM32CubeMX + STM32CubeCLT + OpenOCD + Codex CLI

2. 推荐系统

新手优先：

Ubuntu 24.04 LTS。
Ubuntu 22.04 LTS。
Debian 12。

不建议一开始使用特别小众的发行版，因为教程和依赖少。

3. 安装基础工具

Ubuntu / Debian：

sudoaptupdatesudoaptinstall-ygitcurlwgetunzipbuild-essential cmake ninja-buildmakegdb

安装 OpenOCD：

sudoaptinstall-yopenocd

安装 Arm GCC：

sudoaptinstall-ygcc-arm-none-eabi gdb-multiarch

验证：

arm-none-eabi-gcc--versionopenocd--versioncmake--versionninja--version

如果gcc-arm-none-eabi版本太旧，可以改用 ARM 官方工具链或 STM32CubeCLT。

4. 安装 STM32CubeMX 和 STM32CubeCLT

4.1 STM32CubeMX

从 ST 官网下载 Linux 版本。通常是.zip或.sh安装包。

示例：

chmod+x SetupSTM32CubeMX-*.linux ./SetupSTM32CubeMX-*.linux

安装后可能在：

/opt/STMicroelectronics/STM32Cube/STM32CubeMX/

4.2 STM32CubeCLT

STM32CubeCLT 提供完整命令行工具。安装后确认：

find/opt-namearm-none-eabi-gcc2>/dev/null

如果找到了，把路径加入~/.bashrc：

exportPATH="/opt/st/stm32cubeclt_*/GNU-tools-for-STM32/bin:$PATH"

注意：星号在.bashrc里不一定按你期待展开，实际使用时请写真实路径。

5. 配置 ST-LINK 的 Linux USB 权限

Linux 下普通用户可能没有权限访问 ST-LINK。

现象：

Error: open failed Error: unable to open ftdi device Error: libusb_open() failed with LIBUSB_ERROR_ACCESS

解决思路：

安装 udev 规则。
把用户加入相关组。
重新插拔 ST-LINK。

常见操作：

sudousermod-aGplugdev$USER

然后安装 ST 官方或 OpenOCD 提供的 udev rules。不同系统路径不同，常见位置：

/etc/udev/rules.d/

刷新：

sudoudevadm control --reload-rulessudoudevadm trigger

重新插拔 ST-LINK，并重新登录系统。

6. 安装 CLion

推荐用 JetBrains Toolbox 安装，也可以下载 tar.gz。

安装后启动：

clion

如果命令不存在，从 JetBrains Toolbox 启动即可。

7. 配置 CLion 工具链

进入：

File -> Settings -> Build, Execution, Deployment -> Toolchains

配置：

C Compiler: /usr/bin/arm-none-eabi-gcc C++ Compiler: /usr/bin/arm-none-eabi-g++ Debugger: /usr/bin/gdb-multiarch 或 arm-none-eabi-gdb CMake: bundled Build Tool: ninja

再进入：

File -> Settings -> Build, Execution, Deployment -> Embedded Development

检查：

OpenOCD: /usr/bin/openocd STM32CubeMX: 你的 STM32CubeMX 路径

8. 创建 STM32 CMake 工程

File -> New -> Project。
选择STM32CubeMX。
打开 CubeMX。
选择芯片。
配置SYS -> Debug -> Serial Wire。
配置 LED 引脚为 GPIO Output。
Project Manager -> Toolchain / IDE选择CMake。
Generate Code。
回到 CLion 导入工程。

工程目录：

blink_linux/ CMakeLists.txt blink_linux.ioc Core/ Drivers/ cmake/

9. 用 CLion 编译和调试

编译：

Build -> Build Project

调试：

Run -> Edit Configurations -> OpenOCD Download & Run

常见 OpenOCD 配置：

interface/stlink.cfg target/stm32f1x.cfg

NUCLEO 板可能有 board 配置：

board/st_nucleo_f103rb.cfg

命令行手动测试 OpenOCD：

openocd-finterface/stlink.cfg-ftarget/stm32f1x.cfg

如果成功，会看到监听端口：

Info : Listening on port 3333 for gdb connections

10. 安装 Codex CLI

OpenAI 官方文档说明，Codex CLI 是运行在本地终端的编码代理，可以读取、修改、运行当前目录中的代码。官方安装方式包括 npm 和 Homebrew。Codex CLI 官方支持 macOS 和 Linux，Windows 支持是实验性的，Windows 更推荐 WSL2。

Linux 上推荐 npm：

sudoaptinstall-ynodejsnpmsudonpmi-g@openai/codex

验证：

codex--version

启动：

cd~/embedded/blink_linux codex

第一次运行会提示登录。可以使用 ChatGPT 账号或 API key。

11. Codex CLI 和 CLion 怎么配合

推荐分工：

工具	负责
CLion	编辑、索引、跳转、断点调试、外设寄存器
Codex CLI	读工程、改代码、查编译错误、生成文档、重构
OpenOCD/GDB	下载和调试
Git	保存每次可工作的版本

实际工作流：

CLion 打开工程 | v 终端 cd 到同一工程目录 | v 运行 codex | v 让 Codex 修改代码 | v 回 CLion 查看 diff、Build、Debug

12. 给 Codex 的工程规则

在工程根目录创建：

AGENTS.md

内容示例：

# Project Rules This is an STM32CubeMX generated STM32 embedded project opened with CLion. Rules: - Prefer HAL APIs unless the user explicitly asks for LL or register-level code. - Only edit user-owned code by default. - Keep code inside `/* USER CODE BEGIN */` and `/* USER CODE END */` blocks when editing CubeMX generated files. - Do not modify startup files, linker scripts, generated Drivers, or system clock code unless explicitly requested. - After changes, suggest the exact CLion build/debug step or command-line build command. - Keep beginner-friendly explanations in Chinese when the user asks in Chinese.

13. Codex 提示词模板

13.1 解释工程

请阅读这个 STM32CubeMX + CLion CMake 工程。 我是新手，请用中文解释： 1. CMakeLists.txt 做了什么。 2. Core/Src/main.c 的执行流程。 3. 哪些文件是 CubeMX 生成的，不建议手改。 4. 我应该在哪里写 LED、按键、串口业务代码。

13.2 添加 LED 模块

请在这个 STM32 工程中添加 LED 模块。 要求： 1. 新建 Core/Inc/app_led.h 和 Core/Src/app_led.c。 2. 使用 HAL_GPIO_TogglePin。 3. main.c 只在 USER CODE 区域调用 App_LED_Init 和 App_LED_Tick。 4. 如需修改 CMakeLists.txt，请修改并说明。 5. 修改后运行一次 cmake build，如果失败请继续修复。

13.3 查编译错误

刚才 CLion 编译失败，错误如下： 粘贴完整错误。 请先找第一条真正错误，不要被后续连锁错误误导。 请直接修改代码或 CMake 配置，并解释原因。

14. 命令行构建

即使你用 CLion，也建议学会命令行构建。

常用：

cmake-S.-Bbuild-GNinja-DCMAKE_BUILD_TYPE=Debug cmake--buildbuild

如果工程使用 CubeMX 生成的工具链文件，可能需要：

cmake-S.-Bbuild-GNinja-DCMAKE_TOOLCHAIN_FILE=cmake/gcc-arm-none-eabi.cmake cmake--buildbuild

实际文件名以工程为准。

15. 用 Codex 做代码审查

在提交前让 Codex 检查：

请审查我本次修改的 STM32 代码。 重点看： 1. 是否写在 USER CODE 区域。 2. 是否有阻塞太久的 HAL_Delay。 3. 是否在中断里做了不该做的事情。 4. 是否忘记把新 .c 文件加入 CMakeLists.txt。 5. 是否有数组越界、空指针、竞态风险。 只列问题和建议，不要直接修改。

16. Git 工作流

每完成一个可运行功能就提交：

gitinitgitadd.gitcommit-m"initial stm32 cubemx clion project"

加 LED：

gitadd.gitcommit-m"add led blink app"

加串口：

gitadd.gitcommit-m"add uart printf"

为什么要用 Git：

AI 改坏了可以看 diff。
可以回到上一个能跑的版本。
学习过程更有安全感。

17. 常见问题

问题	原因	解决
Codex 命令不存在	没装或 npm 全局路径不在 PATH	检查`npm bin -g`
OpenOCD 权限错误	udev 未配置	配 udev rules，重新插拔
CLion 能编译但不能下载	OpenOCD cfg 错	换 board/target cfg
Codex 修改后 CLion 没刷新	IDE 缓存	回 CLion 等待索引或手动 Reload CMake
新文件没参与编译	CMakeLists 没加源文件	添加`.c`到源文件列表
断点不停	优化级别太高	Debug 配置用`-O0 -g`