本节完成时的 .opengoat 文件夹结构
这些文件夹会在第 1 至第 8 节中逐步建立。 现在看起来是空的也没关系——每一节都会添加你需要的文件。
📁 .opengoat 完整文件夹结构
$env:USERPROFILE\.opengoat\ ← BALIA OS 主目录
├── identity\ ← 第 2 节创建
│ └── team_design.md ← 团队设计文档
├── .env ← 第 3 节创建（API 密钥和 Webhook）
├── workspaces\ ← 第 3 节创建
│ ├── [agentid]\ ← 第 4 节为每个智能体创建
│ │ ├── SOUL.md
│ │ ├── AGENTS.md
│ │ ├── IDENTITY.md
│ │ ├── HEARTBEAT.md
│ │ ├── TOOLS.md
│ │ ├── USER.md
│ │ └── SPEC_[名称].md
│ └── security-guardian\ ← 第 3 节自动部署
├── agents\ ← OpenClaw 配置文件，在第 5 节自动生成
│ └── [agentid]
│ ├── config.json
│ └── models.json
├── memory\ ← 第 6 节创建
│ └── _SKILL_STATUS.md ← 卡带 ON/OFF 列表（唯一权威来源）
└── skills\ ← 第 6 节添加卡带
└── [卡带名称]\
└── SKILL.md这个文件夹是 BALIA OS 的"家"。 所有智能体的身份、记忆和技能都保存在这里。
💡 什么是 API？— 以及为什么你需要它？
把你的 AI 智能体想象成需要在行动前进行思考的员工。
每当智能体分析情况、撰写报告或做出决定时，它都需要调用一次 AI 模型来完成思考。API 就是发起这次调用的通道 —— 也是为其提供动力的燃料。
Chat AI 与 API — 两种不同的东西：
| Chat AI | API | |
|---|---|---|
| 它是什么 | 你的私人管家 | 智能体的思考引擎 |
| 谁使用它 | 你，直接使用 | 你的智能体，自动使用 |
| 计费方式 | 订阅制（固定费率） | 按用量付费（input + output tokens） |
| 推荐方案 | 付费计划 — 更好的推理能力 | 先充值 $5 |
为什么两者都要用？（混合模式）
API 计费基于 input + output tokens —— 发送给智能体的每个词、以及它回复的每个词都会产生少量费用。
这意味着你如何下达指令会直接影响成本。
使用你的 Chat AI（推荐付费计划以获得更好的推理能力）来：
- 在发送给智能体之前先起草清晰、简洁的指令
- 在把长文档交给智能体之前先做摘要
- 提前把任务结构化，这样智能体就不会浪费 token 去猜你想要什么
一条结构良好、200 个 token 的指令，成本远低于一次模糊的、2,000 个 token 的来回沟通。 你的 Chat AI 是战略家，你的智能体是执行者。 这种组合能让 API 成本保持低廉，同时保持输出质量。
开始之前 — API 费用说明
运行 BALIA OS 的智能体需要一个 AI API 密钥，这与 $48 的指南费用是分开的。
你需要准备：
- 一个 Anthropic 账户，至少充值 $5
- 本指南中的所有智能体都使用 Claude Sonnet 5
为什么 $5 就足够起步： Claude Sonnet 5 的价格为每百万输入 token $2、每百万输出 token $10（此为截至 2026 年 8 月 31 日的上市优惠价，之后将恢复为输入 $3 / 输出 $15）。典型的一次智能体会话只会用掉几千个 token，$5 足够你进行几十次学习和试验。
Anthropic API 没有免费额度。 需要绑定信用卡。 充值地址：console.anthropic.com → Billing → Add credits（最低 $5）
这是运行 BALIA OS 所需的唯一外部费用。 换个角度想：雇用一名人类助理每月要花 $2,000–$5,000。而你的 AI 团队只需要 $5 的 API 额度就能启动。同样的工作，成本却只是零头。
你将安装的内容
完成本节后，你会准备好以下五样东西：
- VS Code — 用于编辑智能体文件、运行命令的工作区
- Claude Code — 第 1 节混合运作方式中的执行担当，在 VS Code 内自动完成错误修复和文件编辑。如果你已经订阅 Claude Pro，无需额外购买
- Node.js — 运行 OpenClaw 和 Claude Code 所必需
- OpenClaw — 驱动 BALIA OS 的 AI 智能体框架
- Anthropic API 密钥 — 智能体用来思考的 AI 引擎
- 安全守护程序 — 自动管理文件、验证配置的自动化设置助手
本节的使用方式： 复制下面的提示词，粘贴到你使用的 Chat AI 中。AI 会全程引导你完成安装 —— 询问你的操作系统、逐步带你完成每一步，并在出问题时帮你解决。如果在任何环节卡住了，只需向 AI 描述问题，它会帮你处理。
▶ 将此粘贴到你的 AI 中以开始
你正在帮助我安装和设置 BALIA OS —— 一个基于 OpenClaw 构建的多智能体 AI 操作系统。
你的任务是一步一步引导我完成安装。每次只问我一个问题，等我回答后再继续。如果我遇到错误，先帮我解决再继续。
以下是我们需要按顺序安装和设置的所有内容：
步骤 1 — 检查我的操作系统
问我："你使用的是 Windows 还是 Mac？"
之后所有步骤都根据我的操作系统给出对应的指示。
步骤 2 — 安装 VS Code
引导我从 code.visualstudio.com 安装 VS Code
- Windows：下载并运行安装程序，确保勾选 "Add to PATH"。
- Mac：下载、解压、拖到 Applications，然后运行 shell 命令把 "code" 添加到 PATH：
Cmd+Shift+P → "Shell Command: Install 'code' command in PATH"
安装完成后，让我在 VS Code 中打开终端并运行：
code --version
问我显示了什么。如果有错误，帮我解决。
步骤 2b — 切换 VS Code 显示语言（可选）
VS Code 默认是英文界面，如果英文对我来说没问题，就告诉我可以完全跳过此步骤，
直接进入步骤 3。
如果我想切换成其他显示语言，引导我：
1. 打开扩展面板（Windows: Ctrl+Shift+X / Mac: Cmd+Shift+X）
2. 搜索我想要的语言包（例如微软出品的 "Chinese (Simplified) Language Pack"，
扩展 ID：MS-CEINTL.vscode-language-pack-zh-hans）并安装
3. 出现提示时点击 "Change Language and Restart"
（若未弹出，可按 Ctrl+Shift+P → "Configure Display Language"）
4. 确认 VS Code 已用新语言重启
步骤 3 — 安装 Python
在 VS Code 终端中，让用户运行：
python --version
如果显示 "Python 3.x.x"，说明 Python 已安装，进入下一步骤。
如果没有，告诉用户从 https://www.python.org/downloads/ 下载安装。
- Windows：运行安装程序，务必勾选 "Add Python to PATH"。
- Mac：运行安装程序，按默认设置一路完成。
安装完成后，重启 VS Code，再次运行 python --version 确认成功。
步骤 4 — 安装 Node.js
引导我从 nodejs.org 安装 Node.js 22 或更高版本（LTS 版本）。
安装后，让我运行：node --version
问我显示了什么。
- 如果是 v22 或更高：很好，继续。
- 如果低于 v22：引导我用 nvm（Mac/Linux）或 nvm-windows（Windows）升级。
- 如果报错：帮我排查。
步骤 5 — 安装 OpenClaw
引导我在 VS Code 终端中运行：
npm install -g openclaw
然后验证：
openclaw --version
常见错误处理：
- Mac 上的 EACCES：引导修复 npm 全局前缀
- "openclaw not found"：让我关闭并重新打开终端，再试一次
步骤 5b — 安装 Claude Code
首先向我说明：
"Claude Code 是第 1 节混合运作方式中的执行担当。
它会直接在 VS Code 中读取错误，并为你处理文件修复和命令执行。
如果你已经订阅 Claude Pro 或更高方案（$20/月起），无需额外购买 ——
claude.ai 的聊天和 Claude Code 共用同一个订阅、同一份用量额度。
如果你在第 1 节选择的 Chat AI 就是 Claude Pro，可以直接用同一账号登录。
如果你的 Chat AI 是 Claude 以外的产品（如 ChatGPT、Gemini），
使用 Claude Code 就需要单独订阅 Claude Pro 或更高方案，或使用 Anthropic API 访问权限。"
然后引导我：
1. 在 VS Code 终端安装 CLI：
npm install -g @anthropic-ai/claude-code
2. 验证安装：
claude --version
确认显示了版本号
3. 在 VS Code 扩展面板（Ctrl+Shift+X）中搜索 "Claude Code"（发布者：Anthropic）并安装
4. 在 VS Code 终端运行以下命令完成首次登录：
claude
会打开浏览器窗口 —— 引导我用 Claude Pro 账号（或 API 密钥）登录
5. 登录完成后，确认终端已回到命令提示符
常见错误处理：
- npm install 出现 EACCES（Mac/Linux 权限错误）：引导我依次运行：
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH
然后重试。
- "claude: command not found"：让我关闭并重新打开终端，再试一次。
- 登录页面无法打开：让我确认在 console.anthropic.com 上是否有有效的订阅或 API 访问权限。
步骤 6 — 获取 Anthropic API 密钥
首先向我说明：
"BALIA OS 默认使用 Claude（Anthropic）作为智能体的 AI 引擎。
现在我们只设置 Claude，其他 AI 引擎可以根据你之后想构建的内容再添加：
- 在创建你自己的卡带（第 6 节）时，你会为该卡带选择最合适的 AI ——
例如 YouTube 用 Gemini（可直接分析视频），销售文案用 GPT-4o。
- BALIA Skill Market 开放后，你还可以安装其他用户构建的卡带，
每个卡带都有自己推荐使用的 AI 引擎。"
然后引导我：
1. 打开 console.anthropic.com
2. 注册或登录
3. 进入 API Keys → Create Key
4. 命名为 "balia-os"
5. 复制密钥（以 sk-ant- 开头）
告诉我："把它保存在安全的地方 —— 你只能看到它一次。"
在继续之前，让我确认已经拿到密钥。
不要让我把密钥粘贴到聊天中。
步骤 7 — 运行 OpenClaw 设置
引导我在 VS Code 终端中运行：
openclaw setup
告诉我接下来会发生什么：
- 它会要求输入 Anthropic API 密钥 —— 在那里粘贴
- 它会自动创建文件夹 ~/.opengoat/（Mac）或
$env:USERPROFILE\.opengoat\（Windows）
这就是 BALIA OS 的主目录 —— 所有智能体文件都存放在这里。
设置完成后，引导我运行以下命令启动 gateway：
Windows: $env:DEBUG="-ciao*"; openclaw gateway --force
Mac: DEBUG="-ciao*" openclaw gateway --force
让我确认看到：
"✓ Gateway running on port 18789"
告诉我："保持这个终端标签页打开 —— 这是你的 gateway。之后所有命令请在新标签页中执行。"
然后让我确认文件夹已创建：
- Windows: dir $env:USERPROFILE\.opengoat
- Mac: ls ~/.opengoat
问我："你看到 .opengoat 文件夹了吗？"
如果没有，帮我排查。
步骤 9 — 创建 .env 文件
引导我在 .opengoat 文件夹中创建一个 .env 文件。
- Windows：在 VS Code 中打开文件夹 $env:USERPROFILE\.opengoat
在左侧面板右键点击 → 新建文件 → 命名为 .env
- Mac：在 VS Code 中打开文件夹 ~/.opengoat
在左侧面板右键点击 → 新建文件 → 命名为 .env
然后粘贴以下模板：
# BALIA OS
BALIA_TOKEN=在此粘贴你的令牌
AGENT_ID=ceo
# Anthropic API
ANTHROPIC_API_KEY=sk-ant-在此粘贴你的密钥
# 智能体模型
CLAUDE_MODEL=claude-sonnet-5
# Discord Webhook —— 在第 4 节填写
# 示例：DISCORD_WEBHOOK_MAYA=https://discord.com/api/webhooks/123456789/xxxxxxxxxxxx
DISCORD_WEBHOOK_[AGENT1NAME]=
DISCORD_WEBHOOK_[AGENT2NAME]=
DISCORD_WEBHOOK_[AGENT3NAME]=
DISCORD_WEBHOOK_[AGENT4NAME]=
DISCORD_WEBHOOK_[AGENT5NAME]=
DISCORD_WEBHOOK_SECURITY=
填写 BALIA_TOKEN：
"查看你购买后收到的邮件，主题行是 'Your BALIA OS Access Token'。
复制令牌（以 BALIA- 开头），粘贴到 BALIA_TOKEN= 后面。
这是你唯一需要手动输入它的地方 ——
第 6 节的安装程序会自动从这个文件读取它。
不要把它粘贴到这个聊天里。"
填写 AGENT_ID：
"这是你 CEO 智能体的 ID —— 也就是你最常对话的主智能体。
这个 ID 是固定的：ceo。请保持 AGENT_ID=ceo 不变，不要修改。
安装脚本和第 4 节都依赖这个值。"
告诉我："Discord webhook 先留空 —— 你会在第 4 节拿到实际的 URL。
URL 格式类似：https://discord.com/api/webhooks/数字/字母
把 [AGENT1NAME] 到 [AGENT5NAME] 替换为你的智能体名称（全部大写）。
DISCORD_WEBHOOK_SECURITY 始终放在最后 —— 它是留给安全守护智能体的。"
安全提示 —— 这样说：
"如果你不想把令牌写进文件里：
可以先跳过 BALIA_TOKEN，在第 6 节安装时再手动输入。"
告诉我："永远不要分享这个文件，也永远不要把它提交到 GitHub。"
步骤 9b — 把 API 密钥写入 .env 文件
说明：这个 API 密钥在步骤 7（openclaw setup）中已经输入过一次，这里解释为什么还需要再写一遍。
这样说："你其实是把同一个 API 密钥设置在两个地方：
- openclaw setup 会把它保存进 OpenClaw 自己的配置里。
- 你的 .env 文件为 BALIA OS 的智能体保存它 —— 智能体直接从 .env 读取自己的密钥。
两处必须使用相同的密钥。这个操作只需要做一次。"
引导我：
1. 在 VS Code 中打开 .env 文件（位于 .opengoat 文件夹中）
2. 找到这一行：ANTHROPIC_API_KEY=sk-ant-在此粘贴你的密钥
3. 把 "sk-ant-在此粘贴你的密钥" 替换为我的实际密钥
4. 保存文件（Windows：Ctrl+S / Mac：Cmd+S）
确认："你的 API 密钥现在已经保存在 .env 文件中。
永远不要分享这个文件，也不要把它提交到 GitHub。"
不要让我把密钥粘贴到聊天中。
完成步骤 9b 后，告诉我："你的环境已经准备好了。接下来我们将设置安全守护程序 —— 你的自动化设置助手。"
现在开始。请先问我第一个问题。🛡️ 先设置好你的安全守护程序
在创建智能体之前，我们会先启动安全守护程序。 从此刻起，安全守护程序会自动检查你的设置， 在需要时把文件移到正确位置，并创建任何缺失的文件。 你不用担心出错 —— 守护程序会替你处理好一切。
🛡️ 部署安全守护程序
⚠️ 警告：API 费用失控风险
【一起真实的海外事件 —— 与 BALIA OS 无关】 2025 年 11 月，一家海外开发团队的 AI 智能体陷入了无限循环， 在无人察觉的情况下持续运行了 11 天， 最终产生了 $47,000 的 API 账单。 （来源：Tech Startups / Hacker News）
AI 智能体有可能在用户毫不知情的情况下持续调用 API。 为防止此类风险，安全守护程序会 24 小时监控费用， 一旦检测到异常，会立即通过 Discord 发送警报。
请务必同时配置以下内容：
- 在你使用的 AI 服务商控制台设置费用提醒（推荐：每日 $3–5） （Anthropic 用户）→ https://console.anthropic.com/settings/billing
- 确认安全守护程序的费用监控设置（步骤 2.5）
你的环境已经准备好了。
BALIA OS 中还有一个智能体：安全守护程序（security-guardian）。
这个智能体由 BALIA 预先配置好。不要更改它的名称、ID 或路径，否则会破坏它与其他智能体之间的集成。
前提条件：安装 PM2
PM2 是 Node.js 的进程管理器。即使电脑重启，它也能让安全守护程序自动继续运行。
打开 VS Code 终端，粘贴以下命令进行安装：
bash
npm install -g pm2如果已经安装了 PM2，可以跳过此步骤。
下载并运行安装程序
💡 什么是 Token？
它是购买后收到的访问链接中，?token= 后面的那串字符。
示例：https://guide.baliaos.com/?token=BALIA-XXXX-XXXX-0001 这种情况下，你的 Token 就是 BALIA-XXXX-XXXX-0001。
如果找不到邮件，请联系客服支持。
第一步 — 下载安装程序
在你的 VS Code 终端中：
Windows：
powershell
Invoke-WebRequest -Uri "https://balia-os-guide.vercel.app/scripts/install_core_pack.py" -OutFile install_core_pack.py
python install_core_pack.pyMac / Linux：
bash
curl -o install_core_pack.py https://balia-os-guide.vercel.app/scripts/install_core_pack.py
python3 install_core_pack.py第二步 — 将安全守护程序注册到 OpenClaw
Windows：
openclaw agents add security-guardian --workspace $env:USERPROFILE\.opengoat\workspaces\security-guardianMac：
openclaw agents add security-guardian --workspace ~/.opengoat/workspaces/security-guardian这会注册 security-guardian，让 OpenClaw 能够向它路由命令。
第 2.5 步 — 验证注册
确认 OpenClaw 能看到这个智能体：
openclaw agents list你应该能看到 security-guardian 出现在列表中。如果没有，重复第二步。
📋 guardian_config.json 自定义指南
以下设置可以随时更改。 文件位置：
$env:USERPROFILE\.opengoat\workspaces\security-guardian\guardian_config.json| 键 | 默认值 | 说明 |
|---|---|---|
cost.alertHourly | 1.0 | 每小时 API 费用提醒（$） |
cost.alertDaily | 5.0 | 每日 API 费用提醒（$） |
rollback.threshold | 6 | 触发回滚所需的文件缺失数量 |
rollback.autoRecovery | true | 自动执行回滚（false = 需人工审批） |
snapshot.intervalMinutes | 10 | 快照频率（分钟） |
snapshot.maxSnapshots | 3 | 保留的快照数量 |
watchdog.checkGateway | true | 监控 OpenClaw gateway |
watchdog.checkWSL2 | false | 监控 WSL2（默认关闭） |
scanner.runIntervalHours | 4 | 检疫扫描频率（小时） |
git.autoPushEnabled | true | 自动备份到 GitHub |
git.autoPushIntervalMinutes | 30 | 备份频率（分钟） |
更改设置后，请重启安全守护程序：
powershell
pm2 restart security-guardian第三步 — 让安全守护程序运行安装程序
openclaw agent --agent security-guardian "Run: python install_core_pack.py --lang zh-CN (token loads from .env automatically). Tell me when done."Token 会从
.env文件中的BALIA_TOKEN自动读取。
智能体会自动执行：
- 验证你的令牌
- 下载安全守护程序文件
- 部署到
.opengoat/agents/security-guardian/和.opengoat/workspaces/security-guardian/ - 在终端显示 "✓ Security Guardian deployed successfully"
⚠️ 重要：不要更改安全守护程序的 ID、名称或文件夹路径。 其他配置文件会直接引用这个智能体。 更改会破坏技能检疫系统。
终端显示 "✓ Security Guardian deployed successfully" 后，继续下面的步骤。
INFO
agents/security-guardian/ 与 workspaces/[agentid]/ 的区别
BALIA OS 为每个智能体使用两种文件夹：
agents/[id]/— OpenClaw 配置文件（config.json、models.json）—— OpenClaw 用它们来启动智能体workspaces/[id]/— 工作区文件（SOUL、AGENTS、IDENTITY、HEARTBEAT、TOOLS、USER、SPEC）—— 智能体在会话开始时读取这些文件
安全守护程序同时使用这两种文件夹：
agents/security-guardian/— config.json 和 models.jsonworkspaces/security-guardian/— SOUL.md、SPEC_SECURITY.md、scripts/ 等
你自己的智能体也使用同样的结构。这两个文件夹都在 $env:USERPROFILE/.opengoat/ 之下。
第 3.5 步 — 停止 gateway，用 PM2 启动 Guardian，然后重启
安装完成后，安全地重启 gateway。
① 停止 gateway
在运行 openclaw gateway 的 PowerShell 窗口中按下：
Ctrl + C如果提示"是否终止？"，按 Y 然后回车。
② 用 PM2 启动安全守护程序
打开一个新的 PowerShell 窗口，逐行运行以下命令：
powershell
pm2 start $env:USERPROFILE\.opengoat\workspaces\security-guardian\scripts\security_guardian.js --name security-guardianpowershell
pm2 start $env:USERPROFILE\.opengoat\workspaces\security-guardian\scripts\watchdog.js --name guardian-watchdogpowershell
pm2 savepowershell
pm2 list确认 security-guardian 和 guardian-watchdog 都显示为 online。
③ 重启 gateway
在同一个 PowerShell 窗口中，逐行运行以下命令：
powershell
$env:DEBUG="-ciao*"powershell
openclaw gateway --force请不要关闭这个 PowerShell 窗口。
▶ 继续：将此粘贴到你的 AI 中
安全守护程序现在已经在运行。让我们创建工作区文件夹并完成设置。
步骤 8 — 为每个智能体创建工作区文件夹
告诉我："我会读取你第 2 节的团队设计文档，自动获取你的智能体 ID。请现在附上它。"
读取附上的团队设计文档。
提取全部 6 个智能体名称/ID（转为小写、去掉空格，空格用连字符替代）。
把列表展示给我：
"我找到了这 6 个智能体：[id1]、[id2]、[id3]、[id4]、[id5]、[id6]
这样对吗？"
等待我确认。
然后一次性给我创建全部 6 个工作区文件夹的确切命令，
把实际 ID 都填好。
使用这种文件夹结构：workspaces\[id]\（不是 workspace-[id]）。
- Windows: cd $env:USERPROFILE\.opengoat
mkdir workspaces\[id1] workspaces\[id2] workspaces\[id3] workspaces\[id4] workspaces\[id5] workspaces\[id6]
- Mac: cd ~/.opengoat
mkdir -p workspaces/[id1] workspaces/[id2] workspaces/[id3] workspaces/[id4] workspaces/[id5] workspaces/[id6]
运行完成后，让我确认文件夹已创建：
- Windows: dir $env:USERPROFILE\.opengoat\workspaces
- Mac: ls ~/.opengoat/workspaces
步骤 10 — 最终检查
逐项和我一起过一遍这份清单：
□ code --version → 显示版本号
□ node --version → 显示 v22 或更高
□ openclaw --version → 显示版本号
□ claude --version → 显示版本号
□ VS Code 已安装 Claude Code 扩展并已登录
□ Gateway 终端显示 "✓ Gateway running"
□ .opengoat 文件夹存在，已确认
□ workspaces/ 下已为全部 6 个智能体创建子文件夹
□ .opengoat 文件夹中存在 .env 文件
□ BALIA_TOKEN 已填写（或已记下将在第 6 节手动输入）
□ AGENT_ID 设置为 ceo
□ ANTHROPIC_API_KEY 已填写
□ 安全守护程序已部署（通过终端输出确认）
全部勾选完成后，说：
"安装完成。你已准备好进入第 4 节 —— 创建你的智能体文件。"
从步骤 8 开始。请我附上团队设计文档。🛡️ 安全守护程序审计
你的安全守护程序现在会检查整个设置，并自动修复发现的问题。
守护程序会检查的内容：
$env:USERPROFILE\.opengoat\下所有必需的文件夹是否存在- 所有必需的文件是否都在正确的位置
- 位置不对的文件会被自动移动
- 缺失的文件会被自动创建（内容为空 —— 你会在第 4 节填写）
守护程序在本节暂不会更改的内容：
- 文件内容（智能体的性格和设置会在第 4 节完成）
运行审计：
Windows:
node $env:USERPROFILE\.opengoat\workspaces\security-guardian\scripts\verify_setup.js --fix守护程序会报告它发现和修复的内容。 如果一切正常，你就可以进入第 4 节了。