OpenClaw本地AI智能体实战：从Node.js筑基到技能链自动化

1. 这不是另一个聊天框：为什么你的第一个AI智能体必须从OpenClaw开始

“AI智能体”这个词最近被刷屏了——微信里冒出一堆“AI助理”，App Store上全是“智能写作Agent”，连NAS后台都开始推荐“本地AI工作流”。但你点开试用，大概率会失望：它能跟你聊天气、写周报、润色邮件，可一旦你说“把上周所有会议录音转成文字，按议题分类，再发给张三李四”，它就卡住了，或者干脆回一句“我无法访问您的文件系统”。

这恰恰是绝大多数人对AI智能体的根本误解：把“能说会道”当成“能干实事”。真正的AI智能体，核心不在“聊”，而在“做”。它得像一个坐在你工位旁的实习生，你一句自然语言指令下去，它能自己打开终端、读取文件、运行脚本、调用API、操作浏览器，最后把结果打包发给你——全程不依赖云端、不上传隐私、不让你手动点十次鼠标。

OpenClaw就是为解决这个断层而生的。它不是模型，不是API封装，而是一个本地执行网关（Local Execution Gateway）。你可以把它理解成AI世界的“USB-C接口”：一端插着你熟悉的Claude、GPT或本地Qwen，另一端则直接连着你的硬盘、终端、浏览器和Git仓库。它的存在，让大模型的“思考能力”第一次真正长出了“手和脚”。

我们团队在2025年11月就开始跟进OpenClaw的早期测试版（当时还叫Moltbot），踩过Windows权限墙、npm策略锁、沙箱隔离失效、技能链断裂等二十多个坑。最惨的一次，是给客户部署时，AI成功生成了代码，却因沙箱默认禁用chmod命令，导致部署脚本没有执行权限，整个服务启动失败——而错误日志里只有一行模糊的EACCES。这种问题，官方文档不会写，Stack Overflow搜不到，只有亲手在Windows PowerShell里反复Set-ExecutionPolicy、在Linux里strace追踪进程、在macOS里codesign重签名二进制文件，才能摸清门道。

所以这篇教程不叫“快速上手”，而叫“保姆级”。它不回避那些让你在凌晨两点对着终端报错发呆的细节：为什么npm : 无法加载文件 ... npm.ps1不是npm坏了，而是Windows安全策略在保护你；为什么openclaw gateway start后浏览器打不开，可能只是3000端口正被Docker Desktop悄悄占着；为什么你装好了file-manager技能，AI却说“我不懂怎么整理文件”，其实是忘了执行最关键的openclaw gateway restart。

它面向的不是“想试试AI”的泛用户，而是已经装过Node.js、写过几行脚本、愿意为自动化多花半小时配置，换来未来每天节省两小时重复劳动的务实派。如果你只想点几下鼠标就拥有一个“智能助手”，那OpenClaw可能不是你的起点；但如果你厌倦了复制粘贴、手动切换窗口、一遍遍敲相同命令，那么今天，就是你第一个真正能“做事”的AI智能体诞生的日子。

2. 环境筑基：Node.js不是摆设，它是OpenClaw的呼吸系统

很多人把Node.js当成一个“安装步骤”，就像装Office一样点下一步。但在OpenClaw的语境里，Node.js远不止于此——它是整个执行网关的运行时心脏与内存调度中枢。OpenClaw的Gateway（网关）、PI-Embedded（本地执行端）全部由Node.js驱动，其V8引擎的异步I/O能力，直接决定了AI指令解析、技能调用、文件读写、进程管理的响应速度。一个配置不当的Node.js环境，轻则导致openclaw doctor诊断失败，重则让AI在执行git pull时卡死在子进程等待状态，最终超时退出。

我们踩的第一个深坑，就出在Node.js版本与权限的双重陷阱上。2026年初，OpenClaw正式要求Node.js 22+ LTS（Long Term Support）。但很多开发者电脑上还留着Node.js 16或18，因为旧项目依赖。当你执行npm i -g openclaw@beta时，npm会尝试编译一些底层C++绑定（比如用于高效文件监控的chokidar），而Node.js 16的N-API版本与OpenClaw新模块不兼容，编译直接报错：

error: ‘napi_get_value_int64’ was not declared in this scope

更隐蔽的是Windows下的PowerShell执行策略。npm : 无法加载文件 c:\program files\nodejs\npm.ps1, 因为在此系统上禁止运行脚本——这条报错90%的新手会误以为npm损坏，其实它暴露的是Windows的安全基石：默认禁止未签名脚本执行。这是微软为防止恶意PowerShell脚本横行而设的硬性防护，不是bug，是feature。强行绕过（如用Set-ExecutionPolicy Unrestricted -Scope CurrentUser）等于拆掉自家防盗门，风险极高。

我们的解决方案是分层击破：

2.1 Node.js安装：拒绝官网一键包，拥抱nvm-windows/macOS/Linux

• Windows用户：放弃nodejs.org下载的.msi安装包。它会把Node.js装进C:\Program Files\nodejs\，这个路径带空格和系统保护，后续npm install全局包时极易触发权限错误。改用 nvm-windows ：

  1. 下载nvm-setup.exe，务必以管理员身份运行；
  2. 安装路径选C:\nvm（无空格、无权限限制）；
  3. 安装完成后，重启终端，执行：

     nvm list available # 查看可用版本 nvm install 22.14.0 # 安装LTS最新版 nvm use 22.14.0 # 切换到该版本 node -v && npm -v # 验证输出 v22.14.0 和 10.9.0

  提示：nvm会将Node.js安装到C:\nvm\v22.14.0\，npm全局模块存于C:\nvm\node_modules，完全避开Program Files的UAC（用户账户控制）拦截。

• macOS用户：别用Homebrew直接brew install node。Homebrew安装的Node.js常与Xcode Command Line Tools的Python路径冲突。改用 nvm ：

  # 先卸载brew版 brew uninstall node # 安装nvm curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 重启终端或执行 source ~/.zshrc nvm install --lts nvm use --lts

• Linux用户（Ubuntu/Debian）：避免apt install nodejs，其版本老旧（常为18.x）。用NodeSource仓库：

  curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - sudo apt-get install -y nodejs

2.2 npm镜像与权限：淘宝源不是万能解药，--location=global才是关键

国内用户必切npm镜像，否则npm i -g openclaw可能卡在fetchMetadata十分钟。但单纯npm config set registry https://registry.npmmirror.com不够。我们发现，当使用nvm时，npm的全局安装路径（prefix）若指向/usr/local，即使切了镜像，仍会因权限不足失败。

正确姿势是：

# 1. 设置镜像（国内首选） npm config set registry https://registry.npmmirror.com # 2. 关键！修改npm全局安装位置到用户目录（彻底规避权限问题） mkdir ~/.npm-global npm config set prefix '~/.npm-global' # 3. 将新prefix加入PATH（以.zshrc为例） echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc source ~/.zshrc # 4. 验证 npm config get prefix # 应输出 /Users/yourname/.npm-global npm list -g openclaw # 应显示空（尚未安装）

注意：npm i -g本质是npm install --location=global。--location=global意味着npm会去prefix指定的目录下查找和安装模块。把prefix挪到用户目录，就等于告诉npm：“所有全局包，都请放在我家书房里，别去闯政府大楼（/usr/local）”。

2.3 终极验证：openclaw doctor背后的五个检查项

安装完Node.js和npm后，别急着装OpenClaw。先运行openclaw doctor（需先npm i -g openclaw@beta），它会执行五项核心检测：

我们曾在一个客户MacBook上遇到spawn ENOENT，排查三天才发现是其IT部门强制启用了System Integrity Protection (SIP)，并禁用了/tmp目录的执行权限。解决方案不是关SIP（高危），而是修改OpenClaw的沙箱根目录：在~/.openclaw/.env中添加SANDBOX_ROOT=/Users/username/openclaw-sandbox。

3. 安装攻坚：三种方式的真相——一键脚本、npm全局、Docker容器，谁在骗你？

OpenClaw官网列出了四种安装方式：一键脚本、npm/pnpm、Docker、源码编译。但作为踩过所有坑的实践者，我必须坦白：没有一种方式是“绝对安全”的，每种都藏着针对不同系统的致命陷阱。选择哪种，取决于你的操作系统、技术栈熟悉度，以及你愿为“省事”付出多少调试成本。

3.1 一键脚本：Windows用户的甜蜜毒药，macOS/Linux的稳定之选

官网推荐的curl -fsSL https://openclaw.ai/install.sh | bash对macOS/Linux极其友好——它本质是拉取GitHub仓库的install.sh，然后执行一系列git clone、npm install、chmod +x操作。整个过程在用户目录下完成，天然规避权限问题。

但Windows的install.cmd却是另一番光景。它试图在PowerShell中模拟Unix行为，而PowerShell的curl（实为Invoke-WebRequest）与Bash的curl参数不兼容。我们实测发现，当网络稍有波动，install.cmd会静默失败，不报错也不退出，卡在Downloading dependencies...。更糟的是，它默认将OpenClaw安装到C:\Program Files\OpenClaw\，再次撞上UAC墙。

我们的Windows安装黄金流程：

# 1. 先解决PowerShell策略（仅需一次） Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser -Force # 2. 手动下载并审查install.cmd（安全第一！） Invoke-WebRequest -Uri "https://openclaw.ai/install.cmd" -OutFile "$env:USERPROFILE\Downloads\install.cmd" # 用记事本打开，确认无`Invoke-Malware`类可疑命令 # 3. 在用户目录下执行（避开Program Files） cd $env:USERPROFILE & "$env:USERPROFILE\Downloads\install.cmd" --tag beta # 4. 若失败，直接退回到npm方式（见下文）

经验：一键脚本适合macOS/Linux新手；Windows用户建议跳过，直奔npm方式。所谓“最快上手”，在Windows上常是“最快崩溃”。

3.2 npm全局安装：最可控，也最考验Node.js功底

npm i -g openclaw@beta是我们的主力安装法。它透明、可审计、易回滚。但“全局安装”四个字背后，是npm机制的精密齿轮咬合：

• npm i -g=npm install --location=global openclaw@beta
• --location=global→ npm去prefix目录（如~/.npm-global）下创建node_modules/openclaw/
• 同时在prefix/bin/下创建软链接openclaw -> ../lib/node_modules/openclaw/bin/openclaw.js

这意味着，openclaw命令能否执行，取决于prefix/bin是否在你的$PATH中。我们见过太多用户npm i -g成功，但终端输入openclaw --version却报command not found，原因就是~/.npm-global/bin没加进PATH。

完整验证链：

# 1. 确认prefix npm config get prefix # 输出应为 /Users/xxx/.npm-global 或 C:\Users\xxx\.npm-global # 2. 确认bin目录存在且有openclaw ls $(npm config get prefix)/bin/openclaw* # macOS/Linux dir %APPDATA%\npm\openclaw* # Windows (若用npm默认prefix) # 3. 确认PATH包含该bin目录 echo $PATH | grep "npm-global" # macOS/Linux echo %PATH% | findstr "npm" # Windows # 4. 若未包含，永久添加（以.zshrc为例） echo 'export PATH=$(npm config get prefix)/bin:$PATH' >> ~/.zshrc source ~/.zshrc

3.3 Docker部署：服务器场景的银弹，个人PC的双刃剑

docker run -d --name openclaw -p 3000:3000 -v ~/.openclaw:/root/.openclaw openclaw/openclaw:latest对云服务器（如阿里云ECS、腾讯云CVM）是完美方案：隔离性好、环境纯净、一键回滚。但对个人Windows/macOS用户，它引入了新维度的复杂性。

• Windows WSL2用户：Docker Desktop会自动启用WSL2后端，~/.openclaw映射到Linux子系统内，路径需用/home/username/.openclaw，而非Windows的C:\Users\xxx\.openclaw。
• macOS M系列芯片用户：Docker镜像若为amd64架构，会通过Rosetta 2转译，性能下降30%，且openclaw gateway start可能因qemu兼容性报错。
• 所有用户共通陷阱：Docker容器内的localhost指向容器自身，而非宿主机。当你在WebUI中配置Ollama模型地址时，不能填http://localhost:11434，而必须填宿主机的Docker网关IP（如http://host.docker.internal:11434）。

我们的建议：个人开发机，用npm方式；生产服务器，用Docker。混用（如在Docker内再跑npm install）是自找麻烦。

3.4 安装后必做的三件事：onboard、gateway start、dashboard的隐藏逻辑

无论哪种方式安装成功，openclaw命令已可用。但此时它只是一个“空壳”，必须完成初始化才能干活：

1. openclaw onboard --flow quickstart：这不是简单的向导。它会：

   • 创建~/.openclaw/config.json（核心配置）
   • 生成~/.openclaw/.env（环境变量，含API Key加密存储）
   • 初始化SQLite数据库~/.openclaw/db.sqlite（存会话、技能状态）
   • 最关键：根据你选择的模型供应商（如Anthropic），自动下载对应SDK依赖（@anthropic-ai/sdk），并验证API Key连通性。

2. openclaw gateway start：启动的是网关服务（Gateway），不是整个OpenClaw。Gateway是消息中枢，负责接收WebUI/飞书/Telegram的指令，分发给Agent，再汇总结果。它监听3000端口（可配），但不启动任何AI模型。模型由Agent按需调用。

3. openclaw dashboard：此命令会：

   • 检查Gateway是否运行（若否，自动start）
   • 获取Gateway的健康状态（/api/health）
   • 自动打开浏览器到http://127.0.0.1:3000（或Docker映射端口）
   • 若端口被占，它不会报错，而是静默失败——这就是为什么你dashboard后浏览器没反应，要立刻lsof -i :3000查端口。

我们曾因onboard时选错模型（误选Ollama但未启动），导致dashboard打开后所有指令都返回Model connection failed。修复只需两步：ollama serve启动Ollama，然后openclaw gateway restart重载配置。

4. 技能激活：ClawHub不是应用商店，它是你的AI工具链装配线

如果把OpenClaw比作一辆车，Gateway是发动机，Agent是驾驶员，那么Skills（技能）就是各种变速箱、差速器和车载冰箱——没有它们，车只能原地空转。clawhub是OpenClaw官方提供的技能包管理器，但它绝非简单的apt install。每个Skill都是一个独立的Node.js子进程，在沙箱中运行，拥有自己的依赖、配置和权限边界。

4.1 ClawHub安装：npm install -g clawhub的权限迷思

clawhub本身是一个npm包，需全局安装。但这里有个精妙设计：clawhub的bin/clawhub.js脚本，会动态读取当前openclaw的安装路径（通过require.resolve('openclaw/package.json')），然后将Skill安装到~/.openclaw/skills/目录下。这意味着，clawhub和openclaw必须由同一套Node.js/npm管理。

常见错误：

• 用nvm安装了OpenClaw（~/.nvm/versions/node/v22.14.0/lib/node_modules/openclaw）
• 却用系统自带npm安装clawhub（/usr/local/lib/node_modules/clawhub）
• 导致clawhub install file-manager时，clawhub找不到openclaw的package.json，报错Cannot find module 'openclaw'

解决方案：始终用同一Node.js版本安装二者：

# 确保在nvm的v22.14.0环境下 nvm use 22.14.0 npm i -g openclaw@beta clawhub@latest

4.2 技能安装的本质：clawhub install做了什么？

以clawhub install file-manager为例，执行后发生以下连锁反应：

1. clawhub从https://hub.openclaw.ai/file-manager拉取Skill元数据（manifest.json），确认版本、依赖、权限需求；
2. 创建~/.openclaw/skills/file-manager/目录；
3. git clone或npm pack下载Skill代码到该目录；
4. 在~/.openclaw/skills/file-manager/下执行npm install，安装其dependencies（如glob,fs-extra）；
5. 将~/.openclaw/skills/file-manager/manifest.json中的permissions字段（如["read:files", "write:files"]）写入~/.openclaw/config.json的skills.file-manager.permissions；
6. 最关键的一步：向正在运行的Gateway进程发送SIGUSR2信号，触发其重新加载skills配置。

这就是为什么clawhub install后，必须openclaw gateway restart——因为restart会完全重启Gateway进程，确保新加载的Skill配置生效。而openclaw gateway reload（热重载）在某些版本中不可靠，尤其当Skill依赖更新时。

4.3 权限沙箱：read:files不是口号，是操作系统级的枷锁

OpenClaw的沙箱（Cell Isolation）不是Node.js的vm模块模拟，而是基于操作系统原生机制的硬隔离：

• Windows：使用Job ObjectsAPI，限制进程可访问的句柄、内存和CPU时间；
• macOS：利用sandbox-exec和com.apple.security.files.user-selected.read-writeentitlements；
• Linux：通过unshare(CLONE_NEWPID)创建PID namespace，并用seccomp-bpf过滤系统调用（如禁用openat以外的文件操作）。

因此，当你在WebUI中看到file-manager技能的权限开关，它控制的是沙箱的seccomp规则白名单。开启read:files，沙箱才允许Skill进程调用openat(AT_FDCWD, "/path/to/file", O_RDONLY)；关闭它，哪怕代码里写了fs.readFileSync('/etc/passwd')，也会在内核层被拦截，返回EPERM。

我们曾为一个金融客户定制bank-report技能，需读取~/Documents/Finance/下的Excel。但沙箱默认只允许读取~/Downloads/。解决方案不是关沙箱（危险！），而是在~/.openclaw/config.json中显式声明：

{ "skills": { "bank-report": { "permissions": ["read:files"], "allowed_paths": ["/Users/finance/Documents/Finance/"] } } }

然后openclaw gateway restart。这是OpenClaw安全哲学的体现：不追求绝对自由，而提供精确可控的权限杠杆。

4.4 实战：三步激活“本地文档整理”技能链

以标题摘要中的“整理项目文档”为例，这不是一个Skill，而是一个Skill组合（Skill Chain）：

1. file-manager：定位、读取、分类文件；
2. code-runner：执行pandoc命令生成README（需提前npm install -g pandoc）；
3. git-operation：提交变更到Git仓库。

安装与配置：

# 1. 安装三个Skill clawhub install file-manager code-runner git-operation # 2. 配置git-operation的SSH密钥（关键！） # 将私钥放入~/.openclaw/ssh/id_rsa，公钥添加到GitHub chmod 600 ~/.openclaw/ssh/id_rsa # 在~/.openclaw/config.json中指定 { "skills": { "git-operation": { "ssh_key_path": "~/.openclaw/ssh/id_rsa" } } } # 3. 重启Gateway，使所有Skill生效 openclaw gateway restart

此时，你在WebUI中发送：“整理~/Projects/my-app/，生成README.md，提交到GitHub”。OpenClaw的Agent会：

• 调用file-manager扫描目录结构；
• 调用code-runner执行pandoc -f markdown -t markdown README.template.md -o README.md；
• 调用git-operation执行git add . && git commit -m "docs: auto-generated README"。

整个过程，file-manager在沙箱中读取文件，code-runner在沙箱中运行pandoc，git-operation在沙箱中执行git——三者互不干扰，权限各守其界。

5. 排查实战：从npm.ps1报错到EACCES，我们如何用strace和Process Monitor定位真凶

部署中最令人抓狂的，不是报错本身，而是错误信息像谜语。npm : 无法加载文件 ... npm.ps1、openclaw : 无法将“openclaw”项识别为 cmdlet、Error: EACCES: permission denied……这些看似相同的报错，根源可能天差地别。下面复盘我们处理过的五个高频“幽灵错误”，展示完整的排查链路。

5.1 错误1：npm : 无法加载文件 c:\program files\nodejs\npm.ps1

表象：PowerShell中执行任何npm命令都报此错。

直觉反应：网上教程说Set-ExecutionPolicy RemoteSigned -Scope CurrentUser就行。

真相：这只是治标。我们发现，当用户同时安装了nvm-windows和官网Node.js时，PowerShell的$env:PATH中会有两条Node.js路径：

C:\Program Files\nodejs\ C:\nvm\

PowerShell按PATH顺序搜索，先找到C:\Program Files\nodejs\npm.ps1，但该文件因UAC被锁定。而C:\nvm\npm.ps1是可执行的，却被忽略了。

排查链路：

1. Get-Command npm→ 显示CommandType: Application, Definition: C:\Program Files\nodejs\npm.ps1
2. echo $env:PATH→ 确认C:\Program Files\nodejs\在C:\nvm\之前
3. Remove-Item "C:\Program Files\nodejs\" -Recurse -Force→ 彻底删除冲突源
4. nvm use 22.14.0→ 确保PATH中只有nvm路径

根本解法：永远只用nvm管理Node.js，卸载所有其他版本。

5.2 错误2：openclaw : 无法将“openclaw”项识别为 cmdlet

表象：npm i -g openclaw成功，但终端不认识openclaw命令。

直觉反应：PATH没配好。

真相：PATH配对了，但openclaw命令是openclaw.cmd（Windows）或openclaw（macOS/Linux）的符号链接，而符号链接指向的openclaw.js路径错了。

排查链路：

1. where openclaw（Windows）或which openclaw（macOS/Linux）→ 找到openclaw.cmd位置
2. 用记事本打开openclaw.cmd，查看其内容：

   @IF EXIST "%~dp0\node.exe" ( "%~dp0\node.exe" "%~dp0\..\openclaw\bin\openclaw.js" %* ) ELSE ( @SETLOCAL @SET PATHEXT=%PATHEXT:;.JS;=;% node "%~dp0\..\openclaw\bin\openclaw.js" %* )

3. 检查%~dp0\..\openclaw\bin\openclaw.js是否存在。若不存在，说明npm i -g时openclaw包没正确解压到node_modules/openclaw/。

根本解法：npm cache clean --force清空缓存，再npm i -g openclaw@beta。有时npm的tarball解压会因网络中断而损坏。

5.3 错误3：openclaw gateway start后，http://127.0.0.1:3000打不开

表象：浏览器显示“连接被拒绝”。

直觉反应：端口被占。

真相：端口确实被占，但占用者不是你猜的Chrome或VS Code，而是Docker Desktop的Kubernetes集群（它默认监听3000端口）。

排查链路：

1. netstat -ano | findstr :3000（Windows）→ 输出TCP 0.0.0.0:3000 0.0.0.0:0 LISTENING 12345
2. tasklist | findstr 12345→ 显示com.docker.backend.exe
3. docker context use default→ 切换Docker上下文，停用Kubernetes
4. 或修改OpenClaw端口：在~/.openclaw/.env中添加PORT=3001，再openclaw gateway restart

经验：在开发机上，永远先lsof -i :3000或netstat -ano | findstr :3000，再动手。

5.4 错误4：clawhub install file-manager成功，但WebUI中技能显示“未启用”

表象：clawhub list能看到file-manager，但WebUI技能管理页是灰色的。

直觉反应：重启Gateway。

真相：clawhub install写入了config.json，但Gateway进程的内存中还缓存着旧配置。openclaw gateway restart会杀死进程并重启，但openclaw gateway reload（热重载）在v2.3.0前有bug，不重载skills部分。

排查链路：

1. cat ~/.openclaw/config.json | jq '.skills."file-manager"'→ 确认enabled字段为true
2. openclaw gateway status→ 查看Gateway进程PID
3. kill -USR2 <PID>→ 手动发送重载信号（USR2是Node.js标准热重载信号）
4. 若无效，则openclaw gateway stop && openclaw gateway start

根本解法：永远用openclaw gateway restart，不用reload。

5.5 错误5：执行file-manager时，报Error: EACCES: permission denied, mkdir '/Users/xxx/Projects'

表象：AI能读取文件，但无法创建目录。

直觉反应：沙箱权限没开。

真相：沙箱权限开了read:files，但没开write:files。更隐蔽的是，mkdir需要父目录的write权限，而/Users/xxx/Projects的父目录/Users/xxx/权限是dr-xr-xr-x（只读），沙箱无法在只读目录下创建子目录。

排查链路：

1. 在WebUI中，进入file-manager技能设置页，确认write:files已勾选；
2. ls -ld /Users/xxx/→ 发现权限为dr-xr-xr-x；
3. sudo chmod u+w /Users/xxx/→ 临时加写权限（不推荐）；
4. 正确解法：在~/.openclaw/config.json中，为file-manager指定allowed_paths到一个有写权限的目录：

   { "skills": { "file-manager": { "allowed_paths": ["/Users/xxx/Downloads/", "/Users/xxx/Documents/Projects/"] } } }

终极工具：Windows用 Process Monitor ，过滤Path包含openclaw和Result为ACCESS DENIED的事件；macOS/Linux用strace -f -e trace=mkdir,openat -p <PID>，实时追踪进程的系统调用失败点。这才是工程师的排错本能。

6. 从零到一：部署你的第一个AI智能体——一个真实可运行的端到端案例

现在，让我们把所有碎片拼成一幅完整图景。以下是一个在macOS上，从空白系统到AI自动整理文档的端到端实操，每一步都经过我们团队在M2 MacBook Pro上的实测。它不跳过任何一个“理所当然”的环节，包括那些让你想砸键盘的细节。

6.1 前置准备：一张干净的白纸

• 系统：macOS Sonoma 14.5
• 目标：让AI自动整理~/Downloads/ProjectDocs/下的PDF和DOCX，按类型归类到~/Documents/SortedDocs/，生成SUMMARY.md，并发送邮件。

6.2 步骤1：安装nvm与Node.js 22.14.0（12分钟）

# 1. 安装nvm curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.zshrc # 2. 安装Node.js LTS nvm install --lts nvm use --lts # 3. 验证 node -v # v22.14.0 npm -v # 10.9.0

注意：source ~/.zshrc后，若nvm命令未找到，重启终端或执行export NVM_DIR="$HOME/.nvm"。

6.3 步骤2：配置npm到用户目录（3分钟）

# 创建全局模块目录 mkdir ~/.npm-global # 配置npm prefix npm config set prefix '~/.