diff --git a/ros2/README.md b/ros2/README.md
new file mode 100644
index 0000000..8e01f13
--- /dev/null
+++ b/ros2/README.md
@@ -0,0 +1,98 @@
+# ros2 — ROS 2 工作空间
+
+## 环境搭建
+
+支持以下三种安装方式，任选其一。
+
+### 方式一：Conda (robostack，跨平台)
+
+适用于 Linux / macOS / Windows，无需 root 权限。
+
+```bash
+# 安装 Miniconda
+wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
+bash Miniconda3-latest-Linux-x86_64.sh
+
+# 创建 ROS 2 Humble 环境
+conda create -n ros2_humble -c robostack-staging -c conda-forge ros-humble-desktop
+conda activate ros2_humble
+
+# 安装构建工具
+conda install -c robostack-staging -c conda-forge \
+    colcon-common-extensions \
+    ros-humble-ament-cmake \
+    python3-pip
+
+# Python 依赖
+pip install pynput
+```
+
+### 方式二：apt 原生安装 (Ubuntu 22.04)
+
+官方推荐的 Ubuntu 安装方式，系统级集成。
+
+```bash
+# 添加 ROS 2 源
+sudo apt update && sudo apt install curl gnupg lsb-release
+sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key \
+    -o /usr/share/keyrings/ros-archive-keyring.gpg
+echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] http://packages.ros.org/ros2/ubuntu $(lsb_release -cs) main" \
+    | sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null
+
+# 安装 ROS 2 Humble
+sudo apt update
+sudo apt install ros-humble-desktop python3-colcon-common-extensions
+
+# Python 依赖
+pip install pynput
+
+# 环境配置（或写入 ~/.bashrc）
+source /opt/ros/humble/setup.bash
+```
+
+### 方式三：Docker
+
+推荐用于 CI/CD 或快速体验，无需污染宿主机环境。
+
+```bash
+# 拉取镜像
+docker pull osrf/ros:humble-desktop
+
+# 启动容器（挂载工作空间）
+docker run -it --rm \
+    -v $(pwd)/ros2:/ws \
+    osrf/ros:humble-desktop \
+    bash
+
+# 容器内安装依赖
+apt update && apt install -y python3-colcon-common-extensions python3-pip
+pip install pynput
+```
+
+## 构建
+
+```bash
+cd ros2
+colcon build --symlink-install --packages-select udp_teleop
+source install/setup.bash
+```
+
+> `--symlink-install`：修改 Python 源文件后无需重新构建，直接生效。
+
+## 运行
+
+```bash
+ros2 run udp_teleop keyboard_control \
+    --ros-args --params-file src/udp_teleop/config/params.yaml
+```
+
+也可以通过命令行覆盖参数：
+
+```bash
+ros2 run udp_teleop keyboard_control \
+    --ros-args -p udp_ip:=192.168.1.100 -p udp_port:=9999
+```
+
+## 包文档
+
+详见 [src/udp_teleop/README.md](src/udp_teleop/README.md)，包含按键映射、UDP 协议、参数配置等。