完成后的状态
你的电脑上有一份可用的 TuyaOpen 代码，并在终端中激活了 tos.py 命令。后续每一篇教程 —— 编译、烧录、配网 —— 都默认你已完成本页。
tos.py是配置、编译、烧录、监听 TuyaOpen 项目的唯一命令行工具。- 激活会在仓库内创建 Python 虚拟环境（
.venv），不会影响系统 Python。 - 每次打开新终端都需要重新激活
tos.py。
准备工作
开始前请准备好以下物品：
- 一块 TuyaOpen 兼容的开发板或模组。
- 一根 USB 数据线（仅充电线不可用）。
- 一台运行 Windows、macOS 或 Linux 的电脑。
安装工具链
TuyaOpen 依赖 git、Python 3、make、cmake 和 ninja。选择你的操作系统，下方的安装命令与激活命令会随之更新。
克隆 TuyaOpen
从 GitHub 或 Gitee 克隆仓库（中国大陆建议使用 Gitee 以提升速度）。
项目路径中不要包含中文、空格或特殊字符；Windows 下不要将项目放在 C 盘。
# 使用 GitHub
git clone https://github.com/tuya/TuyaOpen.git
# 或使用 Gitee
git clone https://gitee.com/tuya-open/TuyaOpen.git
# 进入项目
cd TuyaOpen若克隆较慢，可先调大 git 的 HTTP 缓冲：git config --global http.postBuffer 524288000。
激活 tos.py
在 TuyaOpen 目录中，按你的操作系统运行激活脚本。它会创建 .venv 虚拟环境，并将 tos.py 加入 PATH。
每次重新打开终端都需要再次运行激活命令。
验证是否成功
运行 tos.py version 与 tos.py check。check 会校验工具版本，并在首次运行时下载 SDK 子模块。
❯ tos.py version
[INFO]: Running tos.py ...
[INFO]: v1.3.0
❯ tos.py check
[INFO]: Running tos.py ...
[INFO]: [git] (2.43.0 >= 2.0.0) is ok.
[INFO]: [cmake] (4.0.2 >= 3.28.0) is ok.
[INFO]: [make] (4.3 >= 3.0.0) is ok.
[INFO]: [ninja] (1.11.1 >= 1.6.0) is ok.
[INFO]: Downloading submodules...
[INFO]: Download submodules successfully.version输出当前 tag-commit（如v1.3.0）。若显示[Unknown version]，说明仓库无 tag，常见于 fork。check确认 git ≥ 2.0.0、cmake ≥ 3.28.0、make ≥ 3.0.0、ninja ≥ 1.6.0，随后执行git submodule update --init。- 当日工作结束后，运行
deactivate（Linux/Mac）或exit（Windows）退出虚拟环境。
故障排查
Linux 下激活 tos.py 失败
通常是缺少 python3-venv。安装后重试：sudo apt-get install python3-venv。若仍失败，删除 ./.venv 目录后重新激活。
tos.py check 提示工具版本过低
将对应工具升级到所示最低版本（git 2.0.0、cmake 3.28.0、make 3.0.0、ninja 1.6.0）以上，再运行 tos.py check。
check 过程中子模块下载失败
在仓库根目录手动执行 git submodule update --init，再重新运行 tos.py check。
Windows 下 `tos.py config menu` 中方向键失效
这是终端模拟器兼容性问题。使用 cmd 或 PowerShell，或以 h j k l（左/下/上/右）导航。