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

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

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

本教程目标：

text 复制代码

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，推荐：

text 复制代码

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

2. 推荐系统

新手优先：

Ubuntu 24.04 LTS。
Ubuntu 22.04 LTS。
Debian 12。

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

3. 安装基础工具

Ubuntu / Debian：

bash 复制代码

sudo apt update
sudo apt install -y git curl wget unzip build-essential cmake ninja-build make gdb

安装 OpenOCD：

bash 复制代码

sudo apt install -y openocd

安装 Arm GCC：

bash 复制代码

sudo apt install -y gcc-arm-none-eabi gdb-multiarch

验证：

bash 复制代码

arm-none-eabi-gcc --version
openocd --version
cmake --version
ninja --version

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

4. 安装 STM32CubeMX 和 STM32CubeCLT

4.1 STM32CubeMX

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

示例：

bash 复制代码

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

安装后可能在：

text 复制代码

/opt/STMicroelectronics/STM32Cube/STM32CubeMX/

4.2 STM32CubeCLT

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

bash 复制代码

find /opt -name arm-none-eabi-gcc 2>/dev/null

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

bash 复制代码

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

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

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

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

现象：

text 复制代码

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

解决思路：

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

常见操作：

bash 复制代码

sudo usermod -aG plugdev $USER

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

text 复制代码

/etc/udev/rules.d/

刷新：

bash 复制代码

sudo udevadm control --reload-rules
sudo udevadm trigger

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

6. 安装 CLion

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

安装后启动：

bash 复制代码

clion

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

7. 配置 CLion 工具链

进入：

text 复制代码

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

配置：

text 复制代码

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

再进入：

text 复制代码

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

检查：

text 复制代码

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 导入工程。

工程目录：

text 复制代码

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

9. 用 CLion 编译和调试

编译：

text 复制代码

Build -> Build Project

调试：

text 复制代码

Run -> Edit Configurations -> OpenOCD Download & Run

常见 OpenOCD 配置：

text 复制代码

interface/stlink.cfg
target/stm32f1x.cfg

NUCLEO 板可能有 board 配置：

text 复制代码

board/st_nucleo_f103rb.cfg

命令行手动测试 OpenOCD：

bash 复制代码

openocd -f interface/stlink.cfg -f target/stm32f1x.cfg

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

text 复制代码

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：

bash 复制代码

sudo apt install -y nodejs npm
sudo npm i -g @openai/codex

验证：

bash 复制代码

codex --version

启动：

bash 复制代码

cd ~/embedded/blink_linux
codex

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

11. Codex CLI 和 CLion 怎么配合

推荐分工：

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

实际工作流：

text 复制代码

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

12. 给 Codex 的工程规则

在工程根目录创建：

text 复制代码

AGENTS.md

内容示例：

markdown 复制代码

# 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 解释工程

text 复制代码

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

13.2 添加 LED 模块

text 复制代码

请在这个 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 查编译错误

text 复制代码

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

14. 命令行构建

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

常用：

bash 复制代码

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug
cmake --build build

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

bash 复制代码

cmake -S . -B build -G Ninja -DCMAKE_TOOLCHAIN_FILE=cmake/gcc-arm-none-eabi.cmake
cmake --build build

实际文件名以工程为准。

15. 用 Codex 做代码审查

在提交前让 Codex 检查：

text 复制代码

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

16. Git 工作流

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

bash 复制代码

git init
git add .
git commit -m "initial stm32 cubemx clion project"

加 LED：

bash 复制代码

git add .
git commit -m "add led blink app"

加串口：

bash 复制代码

git add .
git commit -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`

18. 新手学习顺序

先不用 Codex，手动跑通 LED。
用 Codex 解释工程。
让 Codex 添加一个很小的功能。
自己在 CLion 里检查 diff。
Build。
Debug。
Git commit。
再进入下一个功能。

这样最稳，不容易被 AI 生成的大段代码带偏。