Sync
This commit is contained in:
Yaojia Wang
@@ -64,7 +64,7 @@ ssh yiukai@192.168.68.108 "mkdir -p ~/.openclaw/workspace-{agent-id} ~/.openclaw
|
|||||||
|
|
||||||
### Step 3: 编写 Bootstrap 文件
|
### Step 3: 编写 Bootstrap 文件
|
||||||
|
|
||||||
在 `~/.openclaw/agents/{agent-id}/agent/` 下创建：
|
**重要**: 所有 .md 文件放在 **workspace** 目录（`~/.openclaw/workspace-{agent-id}/`），**不是** agentDir。agentDir 只放 JSON 配置文件（auth-profiles.json, models.json），由系统自动管理。
|
||||||
|
|
||||||
**AGENTS.md** -- 操作指令、能力定义、工作流程。必须包含：
|
**AGENTS.md** -- 操作指令、能力定义、工作流程。必须包含：
|
||||||
|
|
||||||
|
|||||||
423
4 - Resources/OpenClaw/OpenClaw 架构与配置全览.md
Normal file
423
4 - Resources/OpenClaw/OpenClaw 架构与配置全览.md
Normal file
@@ -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**: `<workspace>/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/<name>` - 自定义映射钩子
|
||||||
|
|
||||||
|
## 环境变量
|
||||||
|
|
||||||
|
```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 创建指南]]
|
||||||
@@ -93,10 +93,11 @@ invest-analyst 不在 agent-to-agent 通信列表中，独立运作。
|
|||||||
|
|
||||||
## Skills
|
## Skills
|
||||||
|
|
||||||
| 技能 | 路径 |
|
| 技能 | 路径 | 说明 |
|
||||||
|------|------|
|
|------|------|------|
|
||||||
| invest-api | `~/.openclaw/skills/invest-api` |
|
| invest-api | `~/.openclaw/skills/invest-api` | 投资 API |
|
||||||
| openclaw-operator | `~/.openclaw/skills/openclaw-operator` |
|
| openclaw-operator | `~/.openclaw/skills/openclaw-operator` | OpenClaw 操作 |
|
||||||
|
| xiaohongshu-mcp | `~/.openclaw/skills/xiaohongshu-mcp` | 小红书 MCP 工具（通过 mcporter 桥接） |
|
||||||
|
|
||||||
## Plugins
|
## Plugins
|
||||||
|
|
||||||
@@ -120,10 +121,10 @@ invest-analyst 不在 agent-to-agent 通信列表中，独立运作。
|
|||||||
- 最新: 2026.3.13
|
- 最新: 2026.3.13
|
||||||
- 建议: `openclaw update` 或 `npm install -g openclaw@latest`
|
- 建议: `openclaw update` 或 `npm install -g openclaw@latest`
|
||||||
|
|
||||||
### 2. Node.js 版本过低
|
### 2. ~~Node.js 版本过低~~ (已解决 2026-03-22)
|
||||||
- 当前: v18.19.1
|
- ~~当前: v18.19.1~~
|
||||||
- 推荐: v22.16+ LTS 或 v24
|
- 已升级到: v22.22.1 (via NodeSource)
|
||||||
- 风险: 可能缺少新功能支持
|
- 升级原因: mcporter 和 mcp-remote 需要 Node.js 20+
|
||||||
|
|
||||||
### 3. Cron 投递失败
|
### 3. Cron 投递失败
|
||||||
- `lastDeliveryStatus: "not-delivered"`
|
- `lastDeliveryStatus: "not-delivered"`
|
||||||
@@ -154,7 +155,7 @@ invest-analyst 不在 agent-to-agent 通信列表中，独立运作。
|
|||||||
## 待办
|
## 待办
|
||||||
|
|
||||||
- [ ] 升级 OpenClaw 到 2026.3.13
|
- [ ] 升级 OpenClaw 到 2026.3.13
|
||||||
- [ ] 升级 Node.js 到 v22 LTS
|
- [x] 升级 Node.js 到 v22 LTS (完成 2026-03-22, v22.22.1)
|
||||||
- [ ] 排查 cron 投递失败问题
|
- [ ] 排查 cron 投递失败问题
|
||||||
- [ ] 调查 invest-analyst stuck 原因
|
- [ ] 调查 invest-analyst stuck 原因
|
||||||
- [ ] 将密钥迁移到环境变量
|
- [ ] 将密钥迁移到环境变量
|
||||||
|
|||||||
Reference in New Issue
Block a user