第 1 课
clone、pnpm 与本机 API/Web 起栈
clone 仓库、安装依赖、写入 Intelligence 密钥，启动 API 与 Web，并用 health 确认 8787。
学习位置仅保存在当前浏览器，有效期 180 天。
clone、pnpm 与本机 API/Web 起栈
clone、pnpm 与本机 API/Web 起栈
本课按 OpenMuse 官方 README「Quick start」整理。
目标：clone 仓库、安装依赖、写入 CopilotKit Intelligence 密钥，启动 API 与 Web，浏览器打开 **http://localhost:8081**，并用 health 接口确认 API。
主要来源：GitHub CopilotKit/OpenMuse · README Quick start
你将得到什么
- 本机 Web UI：
http://localhost:8081 - API health：
http://localhost:8787/api/health返回正常 - 已复制并填写的
.env（至少含 Intelligence 项目密钥） - 对「OpenMuse 跑哪些进程」的清晰图景（本课先不起浏览器 worker）
课前准备
- Node.js 24 LTS（官方 Requirements）。用
node -v确认主版本为 24。 - pnpm 11.19.0（README 钉死版本）。若尚未安装：
corepack enable
corepack prepare pnpm@11.19.0 --activate
pnpm -v
对照结果： pnpm -v 显示 11.19.0（或至少 11.x，以你能通过 --frozen-lockfile 安装为准）。
- 能访问 GitHub；本课需要一个 CopilotKit 账号，以便生成 Intelligence 项目密钥（官方：
npx copilotkit@latest login/project select）。 - 磁盘与网络：首次
pnpm install会拉较多依赖，预留数分钟。
说明： README 写「local sample app needs no model, Google account, or Docker」——指最小聊天样例可不配模型/Google/Docker；但 Rich Threads / 开对话仍依赖服务器侧
CPK_INTELLIGENCE_API_KEY。本课按官方 Quick start 原样配置该密钥。
一、OpenMuse 是什么（30 秒）
OpenMuse 是 CopilotKit 开源的个人 agent 应用（MIT）：
| 部件 | 作用 |
|---|---|
| Expo/Web 客户端 | iOS / Android / Web 聊天与 Computer UI |
| Hono API + 任务 worker | 认证边界、任务引擎、审阅、持久化 |
| Browser worker（可选） | 私有 Playwright/Chromium，token 保护 |
| Linux computer（可选） | Docker 内非 root 终端与 /workspace |
本课只起 API + Web；浏览器 worker 留到下一课。
二、clone 并安装依赖
在终端执行（与官方 README 一致）：
git clone https://github.com/CopilotKit/OpenMuse.git openmuse
cd openmuse
pnpm install --frozen-lockfile
cp .env.example .env
对照结果：
- 当前目录名是
openmuse，存在.env（由.env.example复制）。 pnpm install --frozen-lockfile无 error 退出（exit code 0）。- 能看到
apps/server、apps/mobile、apps/worker等目录（ls apps）。
若 frozen-lockfile 因环境差异失败：先核对 Node/pnpm 版本；仍失败再查 Issues，不要随意删 lockfile 后乱装，以免与文档漂移。
三、登录 CopilotKit 并写入密钥
官方步骤：
npx copilotkit@latest login
npx copilotkit@latest project select
按 CLI 提示在浏览器完成登录并选择（或创建）Intelligence 项目。把生成的 server-only 项目密钥写入 .env：
CPK_INTELLIGENCE_API_KEY=YOUR_CPK_INTELLIGENCE_API_KEY
同时保留 CLI 生成的 CPK_TELEMETRY_ID（README 要求部署与本地服务端环境一并保留；具体键名以你 .env.example 注释为准）。
对照结果：
.env里CPK_INTELLIGENCE_API_KEY不再是空或示例占位。- 不要把该密钥提交进 Git，也不要贴进聊天/截图。
（可选）本课稍后再配模型
带真实模型浏览/推理时，README「Configure the agent and Google」要求例如：
AGENT_BACKEND=model
MODEL=openai/gpt-5
OPENAI_API_KEY=YOUR_OPENAI_API_KEY
提供商与模型 ID 以你账号与 CopilotKit 当时支持列表为准。本课验收以 进程起来 + health 为主；无模型时部分 Chat 能力会失败，属预期。
四、启动 API 与 Web
终端 A — API / 任务 worker（默认同进程）：
pnpm dev
终端 B — Web：
pnpm dev:web
对照结果：
- 浏览器打开 http://localhost:8081，能看到 OpenMuse 界面（登录/访问方式以当前 Alpha UI 为准；Render 部署用
OPENMUSE_ACCESS_KEY，本地样例跟 README「Open localhost:8081」）。 - 另开标签或用 curl 检查 health：
curl -sS http://localhost:8787/api/health
期望：HTTP 成功且返回健康 JSON（具体字段以当前版本为准；关键是 8787 上 /api/health 可访问）。
端口提醒： Web 8081，API 8787，下一课浏览器 worker 8790。不要默认去撞 3000。
五、在 UI 里点一次「无模型」样例（可选）
README「Try it」第一条不依赖外网模型：
- 在 Chat 发送：Complete the permission slip
- 打开任务，填入虚构表单值，查看保存的 PDF 与准备好的回复草稿
- 官方说明：此流程只写本地 mailbox
对照结果： 能打开对应任务卡片，看到本地生成的 PDF/草稿，而不是整页白屏或立刻 401（若 401，回头检查 Intelligence 密钥是否只配在服务端 .env 且已重启 pnpm dev）。
六、本课排错速查
| 现象 | 先检查 |
|---|---|
pnpm: command not found | corepack / 安装 pnpm 11.19.0 |
| Node 版本不对 | 切换到 Node 24 LTS |
| Chat 无法开线程 | CPK_INTELLIGENCE_API_KEY 是否在 API 进程可读的 .env；改完是否重启 |
| 8081 打不开 | pnpm dev:web 是否在跑；是否被代理劫持 localhost |
| 8787 health 失败 | pnpm dev 日志；端口占用 lsof -i :8787 |
本课小结
你已经按官方 Quick start 完成本机最小栈：仓库、依赖、Intelligence 密钥、API+Web。下一课配置 BROWSER_WORKER_URL / WORKER_TOKEN，安装 Chromium，并跑一次带浏览器的任务。
官方原文入口： https://github.com/CopilotKit/OpenMuse （README → Quick start）
