diff --git a/4 - Resources/OpenClaw/OpenClaw Agent 创建指南.md b/4 - Resources/OpenClaw/OpenClaw Agent 创建指南.md index c16c500..b8c5b45 100644 --- a/4 - Resources/OpenClaw/OpenClaw Agent 创建指南.md +++ b/4 - Resources/OpenClaw/OpenClaw Agent 创建指南.md @@ -64,7 +64,7 @@ ssh yiukai@192.168.68.108 "mkdir -p ~/.openclaw/workspace-{agent-id} ~/.openclaw ### Step 3: 编写 Bootstrap 文件 -在 `~/.openclaw/agents/{agent-id}/agent/` 下创建： +**重要**: 所有 .md 文件放在 **workspace** 目录（`~/.openclaw/workspace-{agent-id}/`），**不是** agentDir。agentDir 只放 JSON 配置文件（auth-profiles.json, models.json），由系统自动管理。 **AGENTS.md** -- 操作指令、能力定义、工作流程。必须包含： diff --git a/4 - Resources/OpenClaw/OpenClaw 架构与配置全览.md b/4 - Resources/OpenClaw/OpenClaw 架构与配置全览.md new file mode 100644 index 0000000..c91d6d1 --- /dev/null +++ b/4 - Resources/OpenClaw/OpenClaw 架构与配置全览.md @@ -0,0 +1,423 @@ +--- +created: "2026-03-22" +type: resource +tags: [resource, openclaw, ai-gateway, architecture, reference, homelab] +source: "https://docs.openclaw.ai/ 系统性整理" +--- + +# OpenClaw 架构与配置全览 + +## 概述 + +OpenClaw 是一个自托管 AI 网关，将 30+ 聊天渠道（WhatsApp, Telegram, Discord, Slack, Signal, iMessage, Matrix, Teams 等）连接到 AI 编码代理。支持 35+ 模型提供商、多 agent 隔离路由、技能/插件扩展、定时任务和 webhook 自动化。 + +- 配置文件: `~/.openclaw/openclaw.json`（JSON5 格式，热重载） +- 默认端口: `18789` +- 文档: https://docs.openclaw.ai/ + +## 目录结构 + +``` +~/.openclaw/ +├── openclaw.json # 主配置文件 +├── .env # 环境变量 +├── workspace/ # 默认 agent workspace +├── workspace-{agent-id}/ # 各 agent 独立 workspace +│ ├── AGENTS.md # 操作指令 + 记忆 +│ ├── SOUL.md # 人格/边界/语气 +│ ├── TOOLS.md # 工具使用说明 +│ ├── IDENTITY.md # 名称/风格 +│ ├── USER.md # 用户画像 +│ ├── BOOTSTRAP.md # 一次性引导（运行后删除） +│ ├── MEMORY.md # 记忆 +│ ├── HEARTBEAT.md # 心跳 +│ ├── skills/ # workspace 级技能（最高优先级） +│ │ └── skill-name/SKILL.md +│ └── hooks/ # workspace 级钩子 +├── agents/{agent-id}/ +│ ├── agent/ # agentDir: auth/model 配置 +│ │ ├── auth-profiles.json +│ │ └── models.json +│ └── sessions/ # 会话存储 +│ ├── sessions.json +│ └── {session-id}.jsonl +├── skills/ # managed 技能（中优先级） +│ └── skill-name/SKILL.md +├── hooks/ # managed 钩子 +├── plugins/ # 已安装插件 +├── browser/ # 浏览器数据 +└── xiaohongshu-mcp/ # Docker 部署的 MCP 服务 +``` + +### 关键区分: workspace vs agentDir + +| 目录 | 用途 | 放什么 | +|------|------|--------| +| `workspace-{id}/` | agent 的工作目录 | **所有 .md 文件**、skills/、hooks/ | +| `agents/{id}/agent/` | agent 的状态目录 | auth-profiles.json、models.json | +| `agents/{id}/sessions/` | 会话存储 | 自动生成的 .jsonl 文件 | + +**重要**: Bootstrap 文件（AGENTS.md, SOUL.md 等）必须放在 **workspace** 目录，不是 agentDir。agentDir 只放 JSON 配置文件。 + +## Agent 配置 + +### 添加 Agent + +```json +{ + "agents": { + "defaults": { + "model": { "primary": "anthropic/claude-sonnet-4-6" }, + "workspace": "~/.openclaw/workspace" + }, + "list": [ + { + "id": "agent-id", + "name": "agent-id", + "workspace": "/home/yiukai/.openclaw/workspace-agent-id", + "agentDir": "/home/yiukai/.openclaw/agents/agent-id/agent", + "model": "kimi-coding/k2p5", + "identity": { "name": "显示名称" }, + "groupChat": { + "mentionPatterns": ["<@!?BOT_USER_ID>", "中文名称", "BOT_USER_ID"] + }, + "subagents": { + "allowAgents": ["other-agent-id"] + } + } + ] + } +} +``` + +### Agent 间通信 + +默认禁用，需显式启用: + +```json +{ + "tools": { + "agentToAgent": { + "enabled": true, + "allow": ["agent-a", "agent-b"] + } + } +} +``` + +## 渠道配置 + +### Discord + +```json +{ + "channels": { + "discord": { + "enabled": true, + "groupPolicy": "allowlist", + "accounts": { + "account-id": { + "name": "显示名称", + "enabled": true, + "token": "BOT_TOKEN", + "groupPolicy": "open", + "streaming": "off", + "guilds": { + "GUILD_ID": { + "requireMention": false, + "users": ["OWNER_ID", "BOT_ID"], + "channels": { "CHANNEL_ID": { "allow": true } } + } + } + } + } + } + } +} +``` + +#### DM 策略 + +| 策略 | 说明 | +|------|------| +| `pairing` | 需要配对码（默认） | +| `allowlist` | 仅允许指定用户 | +| `open` | 允许所有 | +| `disabled` | 禁用 DM | + +#### Bot 必需权限 + +View Channels, Send Messages, Read Message History, Embed Links, Attach Files + +#### Bot 必需 Intent + +Message Content Intent（必须），Server Members Intent（推荐） + +### 路由绑定 (Bindings) + +将消息路由到特定 agent: + +```json +{ + "bindings": [ + { + "agentId": "agent-id", + "match": { + "channel": "discord", + "accountId": "account-id" + } + } + ] +} +``` + +匹配优先级: peer > parent-peer > guild+roles > guild > team > account > channel > default + +## Skills 技能系统 + +### 加载优先级（高到低） + +1. **Workspace skills**: `/skills/skill-name/SKILL.md` +2. **Managed skills**: `~/.openclaw/skills/skill-name/SKILL.md` +3. **Bundled skills**: 内置技能 + +### SKILL.md 格式 + +```markdown +--- +name: skill-name +description: "一行描述" +homepage: https://example.com +metadata: { "openclaw": { "emoji": "📕", "requires": { "bins": ["curl"] } } } +--- + +# 技能说明 + +工具定义和使用指南... +``` + +### 技能配置 + +```json +{ + "skills": { + "entries": { + "skill-name": { "enabled": true }, + "other-skill": { "enabled": true, "apiKey": "..." } + }, + "load": { "extraDirs": [], "watch": true } + } +} +``` + +## Plugins 插件系统 + +### 安装 + +```bash +openclaw plugins install plugin-name # 从 npm +openclaw plugins install -l ./local-plugin # 从本地 +``` + +### 插件能力注册 + +| 能力 | 注册方法 | +|------|---------| +| 文本推理 | `api.registerProvider(...)` | +| 语音 | `api.registerSpeechProvider(...)` | +| 图片生成 | `api.registerImageGenerationProvider(...)` | +| 网络搜索 | `api.registerWebSearchProvider(...)` | +| 消息渠道 | `api.registerChannel(...)` | + +### MCP 适配器插件 + +`openclaw-mcp-adapter` 将 MCP 服务器工具注册为原生 agent 工具: + +```json +{ + "plugins": { + "entries": { + "openclaw-mcp-adapter": { + "enabled": true, + "config": { + "servers": [ + { + "name": "server-name", + "transport": "http", + "url": "http://localhost:18060/mcp" + } + ] + } + } + } + } +} +``` + +支持 `stdio`（启动子进程）和 `http`（连接运行中的服务）两种传输方式。 + +## Hooks 钩子系统 + +### 事件类型 + +| 事件 | 触发时机 | +|------|---------| +| `command:new` | /new 命令 | +| `command:reset` | /reset 命令 | +| `command:stop` | /stop 命令 | +| `message:received` | 收到消息 | +| `message:sent` | 发送消息 | +| `agent:bootstrap` | Agent 启动 | +| `gateway:startup` | Gateway 启动 | + +### 内置钩子 + +| 钩子 | 功能 | +|------|------| +| `session-memory` | /new 时保存上下文快照 | +| `bootstrap-extra-files` | 启动时注入额外文件 | +| `command-logger` | 命令审计日志 | +| `boot-md` | 启动时执行 BOOT.md | + +## Cron 定时任务 + +```json +{ + "cron": { + "enabled": true, + "entries": [ + { + "name": "job-name", + "schedule": "0 8 * * 1-5", + "timezone": "Europe/Stockholm", + "agentId": "agent-id", + "message": "执行任务", + "deliver": { + "channel": "discord", + "target": "channel:CHANNEL_ID" + } + } + ] + } +} +``` + +## Subagents 子代理 + +后台生成独立会话执行任务，完成后报告结果。 + +```json +{ + "agents": { + "defaults": { + "subagents": { + "maxSpawnDepth": 1, + "maxConcurrent": 8, + "runTimeoutSeconds": 300, + "allowAgents": ["*"] + } + } + } +} +``` + +命令: `/subagents list|info|log|kill|spawn|send` + +## Session 会话管理 + +### 作用域 + +| 模式 | 说明 | +|------|------| +| `main` | 每个 agent 单一 session | +| `per-peer` | 每个发送者独立 | +| `per-channel-peer` | 每个渠道+发送者独立 | +| `per-account-channel-peer` | 完全隔离 | + +### 重置 + +```json +{ + "session": { + "reset": { + "mode": "idle", + "idleMinutes": 120 + } + } +} +``` + +## Gateway 配置 + +```json +{ + "gateway": { + "port": 18789, + "mode": "local", + "bind": "lan", + "auth": { "mode": "token", "token": "..." }, + "controlUi": { "enabled": true }, + "http": { + "endpoints": { + "chatCompletions": { "enabled": false }, + "responses": { "enabled": false } + } + } + } +} +``` + +### 热重载 + +三种模式: +- `hybrid`（默认）: 安全变更即时生效，关键变更自动重启 +- `hot`: 仅安全变更生效，关键变更需手动重启 +- `restart`: 任何变更都重启 + +## Webhook (外部触发) + +```json +{ + "hooks": { + "enabled": true, + "token": "shared-secret", + "path": "/hooks" + } +} +``` + +端点: +- `POST /hooks/wake` - 入队系统事件 +- `POST /hooks/agent` - 运行隔离的 agent turn +- `POST /hooks/` - 自定义映射钩子 + +## 环境变量 + +```json +{ + "env": { + "API_KEY": "value", + "NODE_TLS_REJECT_UNAUTHORIZED": "0" + } +} +``` + +支持 `${VAR_NAME}` 语法引用环境变量，支持 SecretRef 对象（env/file/exec 来源）。 + +## 诊断命令 + +```bash +openclaw doctor [--fix] # 诊断并修复 +openclaw status --deep # 完整状态审计 +openclaw config validate # 配置校验 +openclaw channels status --probe # 渠道连通性检查 +openclaw gateway probe # Gateway 连通性检查 +openclaw logs --follow # 尾随日志 +``` + +## Related + +- [[OpenClaw-Skill-Reference]] +- [[OpenClaw 部署配置分析]] +- [[OpenClaw Stock Agent 配置详情]] +- [[OpenClaw Agent 创建指南]] diff --git a/4 - Resources/OpenClaw/OpenClaw 部署配置分析.md b/4 - Resources/OpenClaw/OpenClaw 部署配置分析.md index 0b05301..245dadd 100644 --- a/4 - Resources/OpenClaw/OpenClaw 部署配置分析.md +++ b/4 - Resources/OpenClaw/OpenClaw 部署配置分析.md @@ -93,10 +93,11 @@ invest-analyst 不在 agent-to-agent 通信列表中，独立运作。 ## Skills -| 技能 | 路径 | -|------|------| -| invest-api | `~/.openclaw/skills/invest-api` | -| openclaw-operator | `~/.openclaw/skills/openclaw-operator` | +| 技能 | 路径 | 说明 | +|------|------|------| +| invest-api | `~/.openclaw/skills/invest-api` | 投资 API | +| openclaw-operator | `~/.openclaw/skills/openclaw-operator` | OpenClaw 操作 | +| xiaohongshu-mcp | `~/.openclaw/skills/xiaohongshu-mcp` | 小红书 MCP 工具（通过 mcporter 桥接） | ## Plugins @@ -120,10 +121,10 @@ invest-analyst 不在 agent-to-agent 通信列表中，独立运作。 - 最新: 2026.3.13 - 建议: `openclaw update` 或 `npm install -g openclaw@latest` -### 2. Node.js 版本过低 -- 当前: v18.19.1 -- 推荐: v22.16+ LTS 或 v24 -- 风险: 可能缺少新功能支持 +### 2. ~~Node.js 版本过低~~ (已解决 2026-03-22) +- ~~当前: v18.19.1~~ +- 已升级到: v22.22.1 (via NodeSource) +- 升级原因: mcporter 和 mcp-remote 需要 Node.js 20+ ### 3. Cron 投递失败 - `lastDeliveryStatus: "not-delivered"` @@ -154,7 +155,7 @@ invest-analyst 不在 agent-to-agent 通信列表中，独立运作。 ## 待办 - [ ] 升级 OpenClaw 到 2026.3.13 -- [ ] 升级 Node.js 到 v22 LTS +- [x] 升级 Node.js 到 v22 LTS (完成 2026-03-22, v22.22.1) - [ ] 排查 cron 投递失败问题 - [ ] 调查 invest-analyst stuck 原因 - [ ] 将密钥迁移到环境变量