2026 DAO-Code 安装失败怎么办？先查这 5 类问题

终端里已经出现报错，最省时间的做法不是马上重装，而是先确认安装入口、CPU 架构和实际命令名，再检查 API Key 与配置文件；只有确认残留或版本冲突后，才清理重装。

本周建议动作：先保存完整报错，记录安装方式、Mac 芯片、macOS 版本和当前目录。终端提示 command not found 的用户，先看路径与命令入口；启动后无法调用模型的用户，重点检查凭证与配置；Intel Mac 或刚升级旧版本的用户，优先核对架构和残留文件。

先分清：安装失败，还是启动后的调用失败？

DAO-Code 官方仓库目前列出二进制、npm 和源码三类安装路径。二进制安装后运行的是 dao；npm 可以使用 npx dao-code，全局安装后命令仍是 dao；源码方式则需要在仓库目录完成依赖安装、构建和链接。具体命令应以当前官方 README 安装说明为准。

先看错误出现在哪个时间点：

不要把网络超时直接判断成程序损坏。先保存原始输出，再执行下一步。错误被截断后，后续很难判断它属于下载、命令解析，还是模型请求。

第一类：命令找不到，先查入口再查 PATH

DAO-Code macOS 报错 中最容易误判的一类，就是你安装成功了，但当前 shell 根本找不到可执行文件。

先执行：

uname -m
command -v dao
type -a dao
echo "$PATH"

如果使用二进制安装脚本，再检查默认目录：

ls -la ~/.local/bin/dao
~/.local/bin/dao --help

官方安装脚本默认把文件放到 ~/.local/bin，并在该目录不属于 PATH 时给出追加到 ~/.zshrc 的提示；脚本还会按系统和架构选择下载文件。你可以直接查看官方 install.sh 脚本的当前逻辑。

如果你使用 npm，分别验证包和命令：

npm list -g --depth=0 | grep dao
npm prefix -g
npx dao-code --help
dao --help

npx 会在本地或 npm 缓存环境中调用包提供的可执行命令，不等于把命令永久写进你的 PATH。npm 官方文档也说明，包名与可执行文件名不一定完全相同；当包存在多个入口时，直接猜命令名可能失败。可参考npm exec 的官方说明。

判断方式：

• npx dao-code --help 能运行，dao 不能运行：优先修复全局 PATH，不要重装源码。
• ~/.local/bin/dao --help 能运行，command -v dao 没输出：把安装目录加入当前 shell。
• 两者都不能运行：继续查下载文件、权限或架构，不要把问题归因于 API Key。
• type -a dao 显示多个路径：先记录顺序，旧路径可能遮蔽新版本。

第二类：权限拒绝，分别处理文件、终端和系统拦截

权限问题至少有三种。它们的处理动作不同：

先不要执行类似 sudo chmod -R 777 的高风险命令。它会扩大权限范围，无法证明文件来源，也可能掩盖真正的目录错误。

对已经确认来自官方 Release 的本地文件，可以这样查看：

ls -l ./dao
file ./dao
xattr -l ./dao

安装脚本对 macOS 文件执行了移除隔离属性的处理，但这不代表任何从网络下载的二进制都值得直接放行。重新下载前，应先核对官方 Releases 文件列表，确认系统名称、CPU 架构和版本是否匹配。

⚠️ 注意：如果你无法确认文件来自官方仓库或对应 Release，不要用关闭安全机制的方式“修复”启动问题。先删除可疑文件，回到可信来源重新下载。

第三类：Intel Mac 与 Apple Silicon 文件不匹配

DAO-Code Intel Mac 用户最先要确认的是 CPU 架构，而不是 Node.js 版本。执行：

uname -m

常见结果是：

• arm64：Apple Silicon Mac；
• x86_64：Intel Mac。

再检查 DAO-Code 文件：

file "$(command -v dao)"

官方安装脚本将 macOS 文件区分为 dao-darwin-arm64 与 dao-darwin-x64。如果你手动下载了错误架构，常见表现包括无法执行、启动异常，或后续依赖安装失败。

Apple 官方说明，Apple Silicon Mac 可以借助 Rosetta 2 运行部分 x86_64 程序，但这不是把错误架构文件变成原生 arm64 文件。可参考Apple 关于 Rosetta 的安全说明。因此按下面的顺序处理：

• uname -m 是 x86_64：改用 dao-darwin-x64；
• uname -m 是 arm64：改用 dao-darwin-arm64；
• 手动下载不确定：先删除错误文件，改用 npm；
• 使用 npm 仍失败：检查 Node.js 本身的架构与版本，不要混用多个 Node 安装来源。

如果你需要确认 Node.js 版本和架构：

node -v
node -p "process.arch"
which node

DAO-Code README 标明 npm 路径需要 Node.js 20 或更高版本；安装 Node.js 时也要匹配你的 Mac 架构。不要只看 node -v，还要结合 process.arch 和 which node 判断当前终端实际使用的是哪一份 Node.js。

第四类：工具已启动，但 API Key 或配置没有生效

如果你已经进入 DAO-Code 界面，说明安装和启动阶段基本通过。此时再排查 API Key，不要回头删除二进制。

官方 README 说明，首次运行没有检测到密钥时，程序会引导你输入，并保存到 ~/.dao/config.json；也支持通过 --api-key 临时传入。

先确认当前用户和配置文件：

whoami
ls -la ~/.dao
cat ~/.dao/config.json

不要把真实密钥粘贴到工单、聊天记录或公开 Issue。你只需要确认字段是否存在、配置文件是否属于当前用户，以及当前 shell 是否读取了环境变量：

printenv | grep -E 'DAO|DEEPSEEK|API'

可以用临时参数做一次最小验证：

dao --api-key "$YOUR_API_KEY" --provider deepseek "回复：连接测试"

判断逻辑如下：

• 临时参数成功，配置文件方式失败：配置路径、字段或文件权限有问题；
• 配置文件存在，但当前用户读不到：检查文件所有者与权限；
• 工具根本没有进入交互界面：先回到命令、权限或架构问题；
• 工具进入界面，但每次模型请求失败：再检查 API Key 是否有效、账户是否有调用权限。

不要根据网上帖子猜服务端错误码。当前仓库的官方 Issues 页面才是核对已报告问题和版本关联性的合适入口。

第五类：旧版本残留，最后才决定重装

从旧版本升级后，最常见的隐性问题不是“安装包坏了”，而是旧命令仍排在 PATH 前面，或者旧配置继续被新版本读取。

先收集：

type -a dao
command -v dao
find ~/.local/bin -maxdepth 1 -name 'dao*' -ls
ls -la ~/.dao
find . -maxdepth 2 -path '*/.dao/*' -print

如果同时存在二进制、全局 npm 和源码链接，先不要同时删除。记录每个路径，再逐个验证：

/path/to/dao --help
npx dao-code --help

重装前建议完成这份清单：

• [ ] 保存完整报错原文，不只截取最后一行；
• [ ] 记录 uname -m、sw_vers、node -v 和 which node；
• [ ] 记录当前安装方式：二进制、npx、全局 npm 或源码；
• [ ] 备份 ~/.dao/config.json，不要直接删除；
• [ ] 记录 type -a dao 输出，确认是否存在多个入口；
• [ ] 先移除或隔离明确属于旧版本的命令；
• [ ] 重新安装后先执行 dao --help；
• [ ] 再用最小任务验证模型调用；
• [ ] 最后恢复项目配置和权限规则。

如果同一问题在多台 Mac 上复现，优先查看官方 README、package.json 与 Issues 是否已有版本级变化。package.json 能帮助你确认 npm 入口、脚本和运行依赖，不应只凭旧教程判断当前命令。

一张排障顺序表：什么时候修复，什么时候换安装方式？

如果你的本地环境经常被旧版本、多个 Node 路径或团队成员不同配置打断，可以先阅读 Hashvps 帮助中心，把远程开发环境的登录、权限和交接流程固定下来。

本地方案的优点是文件和密钥都在你手上，但它也有明显限制：Intel Mac 可能需要额外处理架构兼容；多套 Node 和二进制会造成 PATH 冲突；团队协作时每个人的旧配置不同，排障结果难以复现。相比之下，按需租用远程 Apple Silicon Mac，可以把环境重置、版本切换和团队交接放到同一台机器上；但如果你要长期稳定运行、必须连接本地硬件或持续占用设备，自购 Mac 仍可能更合适。需要临时恢复 DAO-Code 开发环境时，可先查看 Hashvps 的 Mac 方案详情，再根据实际使用周期决定是否迁移。

进入支持或提交 Issue 前，建议复制下面的模板，减少来回确认：

系统：
macOS 版本：
Mac 架构：arm64 / x86_64
DAO-Code 安装方式：二进制 / npx / npm / 源码
实际执行命令：
node -v：
which node：
type -a dao：
完整报错：
是否能运行 dao --help：
是否能进入交互界面：
是否只有模型请求失败：

先把这些信息整理完整，再决定修复、切换安装路径或重装。这样处理，通常比“删掉全部文件再试一次”更快，也更不容易丢失 API Key、项目权限和旧版本定位线索。