尧图网页设计 
1. 为什么要把 Qwen Code 和 OpenSpec 放在一起用如果你最近在折腾 CLI 里的 AI 驱动开发大概率会碰到两个名字Qwen Code 和 OpenSpec。Qwen Code 是通义千问团队开源的命令行编码代理能读代码库、写代码、跑命令、修 bugOpenSpec 是一个轻量级的规范驱动开发SDD工具把「意图」先固化成规范文档再让 AI 按规范写代码。单独用哪个都能跑但真正让 AI 驱动开发从「玩具」变成「可落地工程」的是这两个东西的组合。我自己的体感是只用 Qwen Code对话一多就容易跑偏AI 改着改着就忘了最初要做什么只用 OpenSpec规范写得很漂亮但落地执行还得手动喂给模型。把 OpenSpec 当作「需求与规范的锚点」把 Qwen Code 当作「执行规范的编码代理」整条链路才闭环。这篇就按安装、配置、接入统一 Key、跑通第一个变更的完整路径来写所有配置骨架都可以直接复制。适合谁看已经在用 CLI 做开发、想引入 AI 代理但被「上下文漂移」折磨的工程师想给团队搭一套规范驱动 AI 工作流的 Tech Lead以及刚接触 Qwen Code、OpenSpec想一次跑通不踩坑的新手。下面所有命令都在 macOS / Linux 实测过Windows 用 WSL 或 Git Bash 同理。2. 前置环境与 TaoToken 统一通道准备2.1 环境基线两个工具都对 Node.js 版本有要求先把基线拉齐能省掉后面一半的报错。组件最低版本检查命令说明Node.js≥ 20.19.0node --versionOpenSpec 硬性要求低于此版本 init 会直接失败npm≥ 10npm --version随 Node 一起装Git任意较新版本git --versionOpenSpec 归档变更时依赖Qwen Codelatestqwen --version全局安装如果 Node 版本不够别硬扛用 nvm 切一下最省事# 安装并切换到 Node 20 LTS nvm install 20 nvm use 20 node --version # 应输出 v20.x.x 或更高2.2 为什么需要 TaoToken 统一 KeyQwen Code 支持两种认证Qwen OAuth浏览器登录免费和 OpenAI 兼容 API。公司电脑、CI 环境、无头服务器上OAuth 那条路基本走不通只能走 API Key。这时候如果每个工具都单独配一家供应商的 Key管理起来很乱Qwen Code 一个 Key、OpenSpec 调用的模型又一个 Key、以后接别的 Agent 还要再配。TaoToken 在这里的作用是提供一个统一的 API 通道一个 Key、一个 Base URL就能覆盖 Qwen Code、OpenSpec 以及后续各种 OpenAI 兼容客户端。你只需要在 TaoToken 控制台创建一个 API Key然后把它填到各个工具的配置里。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册后在控制台生成 Key 即可。注意API Key 属于敏感凭证不要提交到 Git 仓库。建议用环境变量注入或者放在全局配置目录如~/.qwen/而不是项目目录。2.3 拿到 Key 之后先别急着配创建 Key 的路径是控制台里的 API Keys 页面https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。生成后复制那串sk-开头的字符串先存到本地环境变量里后面两个工具都从这里读# 写入 shell 配置macOS/Linux 用 ~/.zshrc 或 ~/.bashrc export TAOTOKEN_API_KEYsk-你的key export TAOTOKEN_BASE_URLhttps://taotoken.net/api执行source ~/.zshrc让它生效然后用echo $TAOTOKEN_API_KEY确认能打印出来。这一步做完后面配置里就可以直接引用变量不用把明文 Key 写死在文件里。3. 安装 Qwen Code 并接入统一 Key3.1 全局安装npm install -g qwen-code/qwen-codelatest qwen --version如果qwen --version报 command not found多半是 npm 全局 bin 目录没进 PATH。用npm config get prefix看一下路径把它加到 PATH 里即可。3.2 settings.json 骨架Qwen Code 的配置分两层全局配置在~/.qwen/settings.json项目级配置在项目根目录的.qwen/settings.json。项目级会覆盖全局级团队协作时把项目级配置提交上去能保证大家行为一致。先建全局配置目录和文件mkdir -p ~/.qwen然后写入~/.qwen/settings.json这是可直接复制的骨架{ auth: { type: openai, apiKey: ${TAOTOKEN_API_KEY}, baseUrl: https://taotoken.net/api, model: qwen3-coder-plus }, tools: { experimental: { skills: true } }, telemetry: { enabled: false } }几个关键点说明一下。auth.type设为openai表示走 OpenAI 兼容协议apiKey用${TAOTOKEN_API_KEY}引用环境变量避免明文baseUrl填 TaoToken 的 API 地址https://taotoken.net/api注意这里不带任何查询参数model按你实际可用的模型名填。tools.experimental.skills设为true是开启 Agent Skill 能力后面 OpenSpec 的斜杠命令要靠它。注意如果你更想用交互式配置直接运行qwen首次启动会引导你输入 API Key、Base URL、Model 三项填的内容和上面 JSON 一致即可。但交互式配置写的是全局文件团队协作还是推荐手动维护项目级 settings.json。3.3 验证 Qwen Code 能连上配置写完跑一个最小请求验证通道qwen -p 用一句话说明什么是规范驱动开发-p是单次提示模式不进入交互界面。如果返回了模型输出说明 Key、Base URL、Model 三项都通了。如果报 401检查环境变量是否在当前 shell 生效如果报 model not found回到控制台确认模型名拼写。4. 安装 OpenSpec 并生成 config.toml4.1 全局安装与版本确认npm install -g fission-ai/openspeclatest openspec --version4.2 在项目中初始化进入你的项目目录再初始化OpenSpec 会把规范目录建在当前项目下cd my-project openspec init初始化过程会问你选择原生支持的 AI 工具。这里选qwen-codeOpenSpec 会在项目里创建.qwen/目录并写入三个斜杠命令配置文件.qwen └── commands ├── openspec-apply.toml ├── openspec-archive.toml └── openspec-proposal.toml同时项目根会生成openspec/目录和受管理的AGENTS.mdopenspec ├── AGENTS.md └── project.mdAGENTS.md是给 AI 代理的引导说明project.md是项目规范约束可以由 AI 生成后再人工修订。4.3 config.toml 骨架OpenSpec 本身不直接持有模型凭证它通过调用 Qwen Code 来执行任务所以模型配置还是落在 Qwen Code 那边。但 OpenSpec 的斜杠命令行为可以在.qwen/commands/*.toml里调整。以openspec-proposal.toml为例一个可用的骨架长这样description 起草 OpenSpec 变更提案 prompt 你正在协助起草一个 OpenSpec 变更提案。 请阅读 openspec/project.md 中的项目约束 然后根据用户描述生成 proposal.md、design.md、tasks.md 三个文件 放入 openspec/changes/变更名/ 目录下。 变更名使用 kebab-case。 openspec-apply.toml和openspec-archive.toml结构相同只是prompt分别改成「按已批准规范实施任务」和「归档变更并合并回源规范」。这三个文件是 OpenSpec 与 Qwen Code 之间的交接层改 prompt 就能微调 AI 的行为。4.4 检查初始化状态openspec list刚初始化完活跃变更列表应该是空的。如果这条命令报错多半是 Node 版本不够或openspec/目录没建成功回到 4.1 重新确认。5. 跑通第一个 AI 驱动开发任务5.1 启动带 Skill 的 Qwen Codeqwen --experimental-skills进入交互界面后输入/skills可以看到当前可用的 Skill 列表。OpenSpec 注册的斜杠命令会出现在这里。如果你在 settings.json 里已经开了tools.experimental.skills也可以直接qwen启动。5.2 起草变更提案在 Qwen Code 交互界面里提交/openspec-proposal 构建一个业务场景 agent 注册中心生成注册表提供新增、编辑和查询功能一个业务场景只有一个生效的智能体AI 会在openspec/changes/下创建一个 kebab-case 命名的变更目录里面包含三个文件openspec/changes/变更名/ ├── proposal.md # 变更提案为什么改、改什么 ├── design.md # 设计怎么改 └── tasks.md # 任务清单拆成可执行步骤5.3 核实与审核回到终端用 OpenSpec 命令检查openspec list # 确认变更目录已创建 openspec validate 变更名 # 校验规范格式 openspec show 变更名 # 查看提案、任务和规范差异validate通过说明格式没问题show让你逐条审阅 AI 的理解是否准确。这一步是整个流程里最值得花时间的AI 写代码快但方向错了返工更贵。5.4 修正偏差如果发现 AI 理解偏了两种改法。一是回到 Qwen Code 里继续对话让它改design.md或proposal.md二是直接手动编辑这三个 Markdown 文件OpenSpec 不锁文件人工修订完全合法。改完再跑一次openspec validate确认格式没坏。5.5 实施任务提案确认后在 Qwen Code 里执行/openspec-apply 开始实施 变更名AI 会读取tasks.md逐项写代码。每完成一项你可以让它更新任务状态。实测下来任务拆得越细AI 执行越稳如果tasks.md里一条任务包含三四个动作AI 容易漏。5.6 归档变更代码验证无误后/openspec-archive 归档 变更名归档会把批准的规范更新合并回openspec/的源规范变更目录移入归档区。这样下一次变更起草时AI 读到的是最新的项目规范而不是散落在历史对话里的临时约定。6. 本篇常见报错排查6.1 qwen 命令找不到npm install -g成功但命令不可用检查npm config get prefix输出的路径是否在 PATH 里。macOS 上常见的是/usr/local/bin或~/.npm-global/bin。6.2 401 Unauthorized三种可能环境变量没生效新开终端或source一下、Key 复制时带了空格、Base URL 写成了带路径的形式。Base URL 只填https://taotoken.net/api不要在后面加/v1或/chat/completions客户端会自己拼。6.3 model not found模型名要和 TaoToken 控制台里可用的名称完全一致大小写敏感。不确定就先在模型对话页面手动选一个确认可用再填回配置https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。6.4 openspec init 卡住或报 Node 版本错误openspec init对 Node 版本卡得很死低于 20.19.0 直接拒绝。用node --version确认不够就 nvm 切。6.5 /openspec-proposal 命令不出现说明 Qwen Code 没加载到.qwen/commands/下的 toml。检查两点一是启动时是否带了--experimental-skills或 settings.json 里开了 skills二是.qwen/commands/是否在项目根目录下而不是全局目录。6.6 openspec validate 报格式错误多半是 AI 生成的 Markdown 结构不符合 OpenSpec 的规范模板。打开报错指向的文件对照openspec/project.md里的约束修一下或者让 Qwen Code 重新生成该文件。7. 把这条链路用起来跑通第一个变更之后你会发现真正省时间的不是「AI 写代码」这个动作而是「规范先锚定、代码后生成」这个顺序。Qwen Code 负责执行OpenSpec 负责约束TaoToken 负责把两者的模型调用收敛到一个 Key 上。三者各司其职链路才稳。如果你打算把这套东西用到长期编码或 Agent 编排上建议直接上 Coding Plan额度更划算适合高频调用https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。接入过程中遇到配置问题接入文档里有各客户端的完整参数说明https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。想先验证模型输出质量再决定用哪个可以直接在模型对话页面试https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。最后一个实操建议把openspec/project.md当成团队规范的一部分认真维护它写得好不好直接决定 AI 每次起草提案时跑偏的概率。这个文件值得你花半小时打磨比调任何 prompt 都管用。 Qwen Code + OpenSpec 实战指南：AI 驱动开发的从安装到落地
1. 为什么要把 Qwen Code 和 OpenSpec 放在一起用如果你最近在折腾 CLI 里的 AI 驱动开发大概率会碰到两个名字Qwen Code 和 OpenSpec。Qwen Code 是通义千问团队开源的命令行编码代理能读代码库、写代码、跑命令、修 bugOpenSpec 是一个轻量级的规范驱动开发SDD工具把「意图」先固化成规范文档再让 AI 按规范写代码。单独用哪个都能跑但真正让 AI 驱动开发从「玩具」变成「可落地工程」的是这两个东西的组合。我自己的体感是只用 Qwen Code对话一多就容易跑偏AI 改着改着就忘了最初要做什么只用 OpenSpec规范写得很漂亮但落地执行还得手动喂给模型。把 OpenSpec 当作「需求与规范的锚点」把 Qwen Code 当作「执行规范的编码代理」整条链路才闭环。这篇就按安装、配置、接入统一 Key、跑通第一个变更的完整路径来写所有配置骨架都可以直接复制。适合谁看已经在用 CLI 做开发、想引入 AI 代理但被「上下文漂移」折磨的工程师想给团队搭一套规范驱动 AI 工作流的 Tech Lead以及刚接触 Qwen Code、OpenSpec想一次跑通不踩坑的新手。下面所有命令都在 macOS / Linux 实测过Windows 用 WSL 或 Git Bash 同理。2. 前置环境与 TaoToken 统一通道准备2.1 环境基线两个工具都对 Node.js 版本有要求先把基线拉齐能省掉后面一半的报错。组件最低版本检查命令说明Node.js≥ 20.19.0node --versionOpenSpec 硬性要求低于此版本 init 会直接失败npm≥ 10npm --version随 Node 一起装Git任意较新版本git --versionOpenSpec 归档变更时依赖Qwen Codelatestqwen --version全局安装如果 Node 版本不够别硬扛用 nvm 切一下最省事# 安装并切换到 Node 20 LTS nvm install 20 nvm use 20 node --version # 应输出 v20.x.x 或更高2.2 为什么需要 TaoToken 统一 KeyQwen Code 支持两种认证Qwen OAuth浏览器登录免费和 OpenAI 兼容 API。公司电脑、CI 环境、无头服务器上OAuth 那条路基本走不通只能走 API Key。这时候如果每个工具都单独配一家供应商的 Key管理起来很乱Qwen Code 一个 Key、OpenSpec 调用的模型又一个 Key、以后接别的 Agent 还要再配。TaoToken 在这里的作用是提供一个统一的 API 通道一个 Key、一个 Base URL就能覆盖 Qwen Code、OpenSpec 以及后续各种 OpenAI 兼容客户端。你只需要在 TaoToken 控制台创建一个 API Key然后把它填到各个工具的配置里。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册后在控制台生成 Key 即可。注意API Key 属于敏感凭证不要提交到 Git 仓库。建议用环境变量注入或者放在全局配置目录如~/.qwen/而不是项目目录。2.3 拿到 Key 之后先别急着配创建 Key 的路径是控制台里的 API Keys 页面https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。生成后复制那串sk-开头的字符串先存到本地环境变量里后面两个工具都从这里读# 写入 shell 配置macOS/Linux 用 ~/.zshrc 或 ~/.bashrc export TAOTOKEN_API_KEYsk-你的key export TAOTOKEN_BASE_URLhttps://taotoken.net/api执行source ~/.zshrc让它生效然后用echo $TAOTOKEN_API_KEY确认能打印出来。这一步做完后面配置里就可以直接引用变量不用把明文 Key 写死在文件里。3. 安装 Qwen Code 并接入统一 Key3.1 全局安装npm install -g qwen-code/qwen-codelatest qwen --version如果qwen --version报 command not found多半是 npm 全局 bin 目录没进 PATH。用npm config get prefix看一下路径把它加到 PATH 里即可。3.2 settings.json 骨架Qwen Code 的配置分两层全局配置在~/.qwen/settings.json项目级配置在项目根目录的.qwen/settings.json。项目级会覆盖全局级团队协作时把项目级配置提交上去能保证大家行为一致。先建全局配置目录和文件mkdir -p ~/.qwen然后写入~/.qwen/settings.json这是可直接复制的骨架{ auth: { type: openai, apiKey: ${TAOTOKEN_API_KEY}, baseUrl: https://taotoken.net/api, model: qwen3-coder-plus }, tools: { experimental: { skills: true } }, telemetry: { enabled: false } }几个关键点说明一下。auth.type设为openai表示走 OpenAI 兼容协议apiKey用${TAOTOKEN_API_KEY}引用环境变量避免明文baseUrl填 TaoToken 的 API 地址https://taotoken.net/api注意这里不带任何查询参数model按你实际可用的模型名填。tools.experimental.skills设为true是开启 Agent Skill 能力后面 OpenSpec 的斜杠命令要靠它。注意如果你更想用交互式配置直接运行qwen首次启动会引导你输入 API Key、Base URL、Model 三项填的内容和上面 JSON 一致即可。但交互式配置写的是全局文件团队协作还是推荐手动维护项目级 settings.json。3.3 验证 Qwen Code 能连上配置写完跑一个最小请求验证通道qwen -p 用一句话说明什么是规范驱动开发-p是单次提示模式不进入交互界面。如果返回了模型输出说明 Key、Base URL、Model 三项都通了。如果报 401检查环境变量是否在当前 shell 生效如果报 model not found回到控制台确认模型名拼写。4. 安装 OpenSpec 并生成 config.toml4.1 全局安装与版本确认npm install -g fission-ai/openspeclatest openspec --version4.2 在项目中初始化进入你的项目目录再初始化OpenSpec 会把规范目录建在当前项目下cd my-project openspec init初始化过程会问你选择原生支持的 AI 工具。这里选qwen-codeOpenSpec 会在项目里创建.qwen/目录并写入三个斜杠命令配置文件.qwen └── commands ├── openspec-apply.toml ├── openspec-archive.toml └── openspec-proposal.toml同时项目根会生成openspec/目录和受管理的AGENTS.mdopenspec ├── AGENTS.md └── project.mdAGENTS.md是给 AI 代理的引导说明project.md是项目规范约束可以由 AI 生成后再人工修订。4.3 config.toml 骨架OpenSpec 本身不直接持有模型凭证它通过调用 Qwen Code 来执行任务所以模型配置还是落在 Qwen Code 那边。但 OpenSpec 的斜杠命令行为可以在.qwen/commands/*.toml里调整。以openspec-proposal.toml为例一个可用的骨架长这样description 起草 OpenSpec 变更提案 prompt 你正在协助起草一个 OpenSpec 变更提案。 请阅读 openspec/project.md 中的项目约束 然后根据用户描述生成 proposal.md、design.md、tasks.md 三个文件 放入 openspec/changes/变更名/ 目录下。 变更名使用 kebab-case。 openspec-apply.toml和openspec-archive.toml结构相同只是prompt分别改成「按已批准规范实施任务」和「归档变更并合并回源规范」。这三个文件是 OpenSpec 与 Qwen Code 之间的交接层改 prompt 就能微调 AI 的行为。4.4 检查初始化状态openspec list刚初始化完活跃变更列表应该是空的。如果这条命令报错多半是 Node 版本不够或openspec/目录没建成功回到 4.1 重新确认。5. 跑通第一个 AI 驱动开发任务5.1 启动带 Skill 的 Qwen Codeqwen --experimental-skills进入交互界面后输入/skills可以看到当前可用的 Skill 列表。OpenSpec 注册的斜杠命令会出现在这里。如果你在 settings.json 里已经开了tools.experimental.skills也可以直接qwen启动。5.2 起草变更提案在 Qwen Code 交互界面里提交/openspec-proposal 构建一个业务场景 agent 注册中心生成注册表提供新增、编辑和查询功能一个业务场景只有一个生效的智能体AI 会在openspec/changes/下创建一个 kebab-case 命名的变更目录里面包含三个文件openspec/changes/变更名/ ├── proposal.md # 变更提案为什么改、改什么 ├── design.md # 设计怎么改 └── tasks.md # 任务清单拆成可执行步骤5.3 核实与审核回到终端用 OpenSpec 命令检查openspec list # 确认变更目录已创建 openspec validate 变更名 # 校验规范格式 openspec show 变更名 # 查看提案、任务和规范差异validate通过说明格式没问题show让你逐条审阅 AI 的理解是否准确。这一步是整个流程里最值得花时间的AI 写代码快但方向错了返工更贵。5.4 修正偏差如果发现 AI 理解偏了两种改法。一是回到 Qwen Code 里继续对话让它改design.md或proposal.md二是直接手动编辑这三个 Markdown 文件OpenSpec 不锁文件人工修订完全合法。改完再跑一次openspec validate确认格式没坏。5.5 实施任务提案确认后在 Qwen Code 里执行/openspec-apply 开始实施 变更名AI 会读取tasks.md逐项写代码。每完成一项你可以让它更新任务状态。实测下来任务拆得越细AI 执行越稳如果tasks.md里一条任务包含三四个动作AI 容易漏。5.6 归档变更代码验证无误后/openspec-archive 归档 变更名归档会把批准的规范更新合并回openspec/的源规范变更目录移入归档区。这样下一次变更起草时AI 读到的是最新的项目规范而不是散落在历史对话里的临时约定。6. 本篇常见报错排查6.1 qwen 命令找不到npm install -g成功但命令不可用检查npm config get prefix输出的路径是否在 PATH 里。macOS 上常见的是/usr/local/bin或~/.npm-global/bin。6.2 401 Unauthorized三种可能环境变量没生效新开终端或source一下、Key 复制时带了空格、Base URL 写成了带路径的形式。Base URL 只填https://taotoken.net/api不要在后面加/v1或/chat/completions客户端会自己拼。6.3 model not found模型名要和 TaoToken 控制台里可用的名称完全一致大小写敏感。不确定就先在模型对话页面手动选一个确认可用再填回配置https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。6.4 openspec init 卡住或报 Node 版本错误openspec init对 Node 版本卡得很死低于 20.19.0 直接拒绝。用node --version确认不够就 nvm 切。6.5 /openspec-proposal 命令不出现说明 Qwen Code 没加载到.qwen/commands/下的 toml。检查两点一是启动时是否带了--experimental-skills或 settings.json 里开了 skills二是.qwen/commands/是否在项目根目录下而不是全局目录。6.6 openspec validate 报格式错误多半是 AI 生成的 Markdown 结构不符合 OpenSpec 的规范模板。打开报错指向的文件对照openspec/project.md里的约束修一下或者让 Qwen Code 重新生成该文件。7. 把这条链路用起来跑通第一个变更之后你会发现真正省时间的不是「AI 写代码」这个动作而是「规范先锚定、代码后生成」这个顺序。Qwen Code 负责执行OpenSpec 负责约束TaoToken 负责把两者的模型调用收敛到一个 Key 上。三者各司其职链路才稳。如果你打算把这套东西用到长期编码或 Agent 编排上建议直接上 Coding Plan额度更划算适合高频调用https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。接入过程中遇到配置问题接入文档里有各客户端的完整参数说明https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。想先验证模型输出质量再决定用哪个可以直接在模型对话页面试https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。最后一个实操建议把openspec/project.md当成团队规范的一部分认真维护它写得好不好直接决定 AI 每次起草提案时跑偏的概率。这个文件值得你花半小时打磨比调任何 prompt 都管用。