本文檔旨在讓你幾乎不需要查看 Source Code，就能完全理解 OpenClaw 這個開源 AI Agent 系統。
- 概述與定位
- 整體架構
- Gateway 系統
- Channel 頻道系統
- Agent 系統
- Provider 系統
- 路由與會話管理
- 工具系統 (Tools)
- 配置系統
- CLI 命令
- 自動回覆系統
- 記憶與上下文
- 媒體處理
- 安全與認證
- Hooks 系統
- 插件與擴展
- 日誌與監控
- 部署與安裝
OpenClaw（原名 Clawdbot → Moltbot → OpenClaw）是一個開源的 AI Agent 系統，由奧地利工程師 Peter Steinberger 於 2025 年 11 月發布。
核心定位：
- 本地運行的 AI Gateway：在你的機器上運行，作為 AI 模型與外部世界的橋樑
- 多頻道訊息整合：連接 WhatsApp、Telegram、Discord、Slack、Signal、iMessage 等通訊軟體
- 自動化任務執行：可執行 shell 命令、檔案操作、網頁自動化等
| 特性 | 說明 |
|---|---|
| 統一入口 | 透過任何通訊軟體傳訊息即可操控電腦 |
| 會話持久化 | 自動保存對話歷史與上下文 |
| 多 Agent 路由 | 不同群組/使用者可對應不同 Agent |
| 模型回退 | 主模型失敗時自動切換備用模型 |
| 可靠執行 | Lane Queue 串行執行防止 race condition |
openclaw/
├── src/ # 核心源碼
│ ├── entry.ts # 程式進入點
│ ├── index.ts # 程式庫匯出
│ ├── cli/ # CLI 層
│ ├── gateway/ # Gateway 閘道層（130+ 檔案）
│ ├── agents/ # Agent 系統（290+ 檔案）
│ ├── channels/ # 頻道系統
│ ├── routing/ # 路由系統
│ ├── config/ # 配置系統
│ ├── commands/ # 命令實現（180+ 檔案）
│ ├── auto-reply/ # 自動回覆
│ ├── memory/ # 記憶系統
│ ├── hooks/ # Hooks 系統
│ ├── plugins/ # 插件系統
│ ├── media/ # 媒體處理
│ ├── infra/ # 基礎設施
│ └── logging/ # 日誌系統
├── extensions/ # 擴展頻道（30+ 個）
├── docs/ # 文檔
├── scripts/ # 腳本工具
├── apps/ # 原生應用（iOS、Android、macOS）
└── test/ # 測試
┌─────────────────────────────────────────────────────────────────┐
│ 使用者介面層 │
│ Telegram │ Discord │ WhatsApp │ Slack │ Signal │ iMessage │
│ │ Matrix │ Teams │ Feishu │ LINE │ ... │
└──────────────────────────┬──────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Gateway Server │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Channel Dock │ │ Router │ │ Session Mgr │ │
│ │ (Adapters) │ │ (Bindings) │ │ (Persist) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Lane Queue │ │ WebSocket │ │ Config │ │
│ │ (Serial Exec)│ │ (Client) │ │ (Reload) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└──────────────────────────┬──────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Agent 執行層 │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Agent Config │ │ Pi Runner │ │ Tools │ │
│ │ (Scope/Model)│ │ (Executor) │ │ (Capabilities)│ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└──────────────────────────┬──────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Provider 層 │
│ Anthropic │ OpenAI │ Google │ Bedrock │ Ollama │ ... │
└─────────────────────────────────────────────────────────────────┘
使用者訊息（如 Telegram）
│
▼
Channel Monitor（監聽訊息）
│
▼
dispatchInboundMessage()（訊息分發）
│
▼
resolveAgentRoute()（決定由哪個 Agent 處理）
│
▼
getReplyFromConfig()（準備回覆配置）
│
▼
runReplyAgent()（執行 Agent）
│
├─→ 呼叫 AI 模型（Claude/GPT/...）
│
├─→ 執行 Tools（如需要）
│
└─→ 生成回覆
│
▼
Channel Outbound（發送回覆到原頻道）
| 模組 | 路徑 | 職責 |
|---|---|---|
| Entry | src/entry.ts |
程式進入點，環境初始化 |
| Gateway | src/gateway/ |
中央樞紐，管理頻道連接、WebSocket 通訊 |
| Channels | src/channels/ |
頻道 Adapter，統一各平台介面 |
| Agents | src/agents/ |
Agent 定義、執行、工具管理 |
| Routing | src/routing/ |
訊息路由，決定哪個 Agent 處理 |
| Config | src/config/ |
配置系統（JSON5 格式） |
| CLI | src/cli/ |
命令列介面 |
| Auto-Reply | src/auto-reply/ |
自動回覆邏輯 |
| Memory | src/memory/ |
會話記憶管理 |
| Hooks | src/hooks/ |
事件鉤子 |
| Extensions | extensions/ |
擴展頻道（Matrix、Teams、Feishu 等） |
Gateway 是 OpenClaw 的核心樞紐，負責管理所有頻道連接和訊息路由。
openclaw gateway run
│
▼
startGatewayServer()
├─→ loadConfig() # 載入配置
├─→ createChannelManager() # 初始化頻道管理器
├─→ attachGatewayWsHandlers() # 設置 WebSocket 處理
├─→ startGatewaySidecars() # 啟動邊車服務
├─→ startGatewayConfigReloader() # 啟動配置熱重載
├─→ startHeartbeatRunner() # 啟動心跳
├─→ startGatewayDiscovery() # 啟動服務發現
└─→ startGatewayMaintenanceTimers() # 啟動維護計時器
| 檔案 | 職責 |
|---|---|
src/gateway/server.impl.ts |
Gateway 伺服器主實現 |
src/gateway/boot.ts |
啟動序列 |
src/gateway/client.ts |
Gateway 客戶端 |
src/gateway/server-ws-runtime.ts |
WebSocket 執行時 |
type GatewayServer = {
// 生命週期
start(): Promise<void>;
stop(): Promise<void>;
isHealthy(): boolean;
// 頻道管理
getChannelManager(): ChannelManager;
// Agent 執行
dispatchMessage(msg: InboundMessage): Promise<void>;
// WebSocket
handleWsConnection(ws: WebSocket): void;
// 配置
reloadConfig(): Promise<void>;
// 事件
on(event: string, handler: Function): void;
};Lane Queue 是 OpenClaw 的核心創新之一，用於確保訊息串行執行，避免 race condition。
訊息 A（使用者 1）──┐
│
訊息 B（使用者 1）──┼──→ Lane Queue（使用者 1）──→ 串行執行
│
訊息 C（使用者 1）──┘
訊息 D（使用者 2）──┐
│
訊息 E（使用者 2）──┼──→ Lane Queue（使用者 2）──→ 串行執行
特點：
- 同一使用者的訊息串行處理（避免衝突）
- 不同使用者的訊息並行處理（提高效率）
- 支援優先級設定
核心頻道（內建）：
telegram- Telegram Bot APIwhatsapp- WhatsApp Web（QR 登入）discord- Discord Bot APIslack- Slack Socket Modesignal- signal-cli 連結裝置imessage- iMessage（macOS）googlechat- Google Chat API
擴展頻道（extensions/ 目錄）：
matrix- Matrix/Synapse 協定msteams- Microsoft Teamsfeishu- 飛書/Larkline- LINE Messagingbluebubbles- BlueBubbles（iMessage 替代）mattermost- Mattermostnextcloud-talk- Nextcloud Talkzalo- Zalo（越南）- 更多...
每個頻道實作統一的 ChannelPlugin 介面：
type ChannelPlugin<ResolvedAccount = any> = {
// 標識
id: ChannelId;
meta: ChannelMeta;
capabilities: ChannelCapabilities;
// 核心 Adapter
config: ChannelConfigAdapter<ResolvedAccount>; // 帳戶管理
setup?: ChannelSetupAdapter; // 初始化設定
security?: ChannelSecurityAdapter; // 安全政策
outbound?: ChannelOutboundAdapter; // 訊息發送
status?: ChannelStatusAdapter; // 狀態查詢
// 訊息處理
messaging?: ChannelMessagingAdapter;
mentions?: ChannelMentionAdapter;
actions?: ChannelMessageActionAdapter;
// 群組與線程
groups?: ChannelGroupAdapter;
threading?: ChannelThreadingAdapter;
commands?: ChannelCommandAdapter;
// 路由
pairing?: ChannelPairingAdapter;
directory?: ChannelDirectoryAdapter;
resolver?: ChannelResolverAdapter;
// Gateway 整合
gateway?: ChannelGatewayAdapter<ResolvedAccount>;
auth?: ChannelAuthAdapter;
elevated?: ChannelElevatedAdapter;
// 其他
streaming?: ChannelStreamingAdapter;
heartbeat?: ChannelHeartbeatAdapter;
agentTools?: ChannelAgentToolFactory;
onboarding?: ChannelOnboardingAdapter;
};type ChannelCapabilities = {
chatTypes: Array<"direct" | "group" | "channel" | "thread">;
polls?: boolean; // 投票功能
reactions?: boolean; // 表情反應
edit?: boolean; // 編輯訊息
unsend?: boolean; // 取消發送
reply?: boolean; // 回覆功能
effects?: boolean; // 視覺效果
groupManagement?: boolean; // 群組管理
threads?: boolean; // 線程支援
media?: boolean; // 媒體支援
nativeCommands?: boolean; // 斜槓命令
blockStreaming?: boolean; // 禁止串流
};| 頻道 | 訊息限制 | 串流 | 線程 | 特色 |
|---|---|---|---|---|
| Telegram | 4096 chars | ❌ | ✅ | Bot 市場、群組管理 |
| Discord | 2000 chars | ✅ | ✅ | 公會/頻道結構、按鈕 |
| 4096 chars | ❌ | ❌ | QR 登入、商業帳戶 | |
| Slack | 40000 chars | ✅ | ✅ | Socket Mode、豐富互動 |
| iMessage | 無限制 | ✅ | ✅ | 原生整合、效果 |
- 在
extensions/建立目錄 - 實作
ChannelPlugin介面 - 實作
resolveAccount()和listAccountIds() - 實作
sendMessage()出站邏輯 - 實作
monitor()入站監聽 - 實作
onboarding登入流程
Agent 是 OpenClaw 中的獨立執行單位，每個 Agent 有自己的：
- 身份（ID、名稱）
- 模型配置
- 工作目錄
- 技能列表
- 會話歷史
type AgentEntry = {
id: string; // Agent ID（如 "main"、"code-agent"）
default?: boolean; // 是否為預設 Agent
name?: string; // 顯示名稱
workspace?: string; // 工作目錄
agentDir?: string; // Agent 資料目錄
model?: AgentModelConfig; // 模型配置
skills?: string[]; // 技能列表
memorySearch?: MemorySearchConfig;
heartbeat?: HeartbeatConfig;
identity?: IdentityConfig;
subagents?: {
allowAgents?: string[]; // 可生成的子 Agent
model?: ModelConfig;
};
sandbox?: SandboxConfig;
tools?: AgentToolsConfig;
};agentCommand(opts)
│
├─→ 驗證輸入（訊息、會話、目標）
│
├─→ loadConfig()
│
├─→ resolveAgentConfig()
│ ├─→ 取得 Agent ID
│ ├─→ 解析工作目錄
│ └─→ 解析模型配置
│
├─→ ensureAgentWorkspace()
│
├─→ loadModelDirectory()
│
├─→ 選擇執行器：
│ ├─→ runCliAgent()（CLI 模式）
│ └─→ runEmbeddedPiAgent()（內嵌模式）
│
└─→ 遞交結果
agent:{agentId}:{channel}:{chatType}:{peerId}
例如：
agent:main:telegram:dm:123456789agent:code-agent:discord:channel:guild-123:channel-456agent:main:slack:thread:workspace-1:channel-2:thread-3
{
"agents": {
"defaults": {
"model": "anthropic/claude-3-5-sonnet"
},
"list": [
{
"id": "main",
"default": true,
"name": "主要助手"
},
{
"id": "code-agent",
"name": "程式助手",
"model": "anthropic/claude-3-opus",
"workspace": "/path/to/code",
"skills": ["code-execution", "git"]
},
{
"id": "research-agent",
"name": "研究助手",
"model": "openai/gpt-4",
"tools": {
"webSearch": { "enabled": true }
}
}
]
}
}| Provider | API 類型 | 說明 |
|---|---|---|
anthropic |
anthropic-messages | Claude 系列 |
openai |
openai-completions | GPT 系列 |
google |
Gemini 系列 | |
bedrock |
bedrock-converse-stream | AWS Bedrock |
ollama |
openai-completions | 本地 Ollama |
minimax |
anthropic-messages | MiniMax AI |
moonshot |
openai-completions | Moonshot (Kimi) |
qwen-portal |
openai-completions | 阿里 Qwen |
venice |
openai-completions | Venice AI |
github-copilot |
自訂 | GitHub Copilot |
{
"models": {
"providers": {
"anthropic": {
"baseUrl": "https://api.anthropic.com",
"apiKey": "${ANTHROPIC_API_KEY}",
"models": [
{ "id": "claude-3-5-sonnet", "contextWindow": 200000 },
{ "id": "claude-3-opus", "contextWindow": 200000 }
]
},
"ollama": {
"baseUrl": "http://localhost:11434",
"models": [
{ "id": "llama3", "contextWindow": 8192 }
]
}
}
}
}// 配置
{
"model": {
"primary": "anthropic/claude-3-5-sonnet",
"fallbacks": [
"anthropic/claude-3-opus",
"openai/gpt-4",
"google/gemini-2-flash"
]
}
}回退流程：
Primary Model
│
├─→ 成功 → 返回結果
│
└─→ 失敗（認證錯誤、Rate Limit）
│
▼
嘗試下一個 Auth Profile
│
└─→ 全部失敗 → 切換到 Fallback #1
│
└─→ 失敗 → Fallback #2 → ...
OpenClaw 會自動檢測可用的 Provider：
- 檢查環境變數（
ANTHROPIC_API_KEY、OPENAI_API_KEY等） - 檢查認證存儲
- 探測本地服務（Ollama）
function resolveAgentRoute(input): ResolvedAgentRoute {
// 1. 列出所有綁定規則
const bindings = listBindings(config);
// 2. 按優先級匹配
for (const binding of bindings) {
if (matchBinding(binding, input)) {
return {
agentId: binding.agentId,
matchedBy: binding.type
};
}
}
// 3. 使用預設 Agent
return { agentId: defaultAgentId, matchedBy: "default" };
}binding.peer- 特定對話/群組binding.peer.parent- 父級線程（線程繼承）binding.guild- Discord 公會binding.team- Slack 工作區binding.account- 特定帳戶binding.channel- 特定頻道類型default- 預設 Agent
{
"bindings": [
{
"agentId": "code-agent",
"match": {
"channel": "telegram",
"peer": { "kind": "group", "id": "dev-group-123" }
}
},
{
"agentId": "support-agent",
"match": {
"channel": "discord",
"guild": "support-guild-456"
}
},
{
"agentId": "main",
"match": {
"channel": "telegram"
}
}
]
}會話資料儲存在：
~/.openclaw/sessions/- 會話檔案~/.openclaw/agents/{agentId}/sessions/- Agent 專屬會話
| 工具 | 說明 | 檔案 |
|---|---|---|
browser |
網頁自動化 | src/agents/tools/browser-tool.ts |
message |
跨頻道訊息發送 | src/agents/tools/message-tool.ts |
cron |
排程任務 | src/agents/tools/cron-tool.ts |
tts |
文字轉語音 | src/agents/tools/tts-tool.ts |
image |
圖片處理/識別 | src/agents/tools/image-tool.ts |
canvas |
圖片生成 | src/agents/tools/canvas-tool.ts |
nodes |
程式碼執行 | src/agents/tools/nodes-tool.ts |
gateway |
Gateway 操作 | src/agents/tools/gateway-tool.ts |
agents.list |
列出 Agent | src/agents/tools/agents-list-tool.ts |
sessions.list |
列出會話 | src/agents/tools/sessions-list-tool.ts |
sessions.history |
會話歷史 | src/agents/tools/sessions-history-tool.ts |
sessions.send |
發送到會話 | src/agents/tools/sessions-send-tool.ts |
sessions.spawn |
生成子 Agent | src/agents/tools/sessions-spawn-tool.ts |
sessions.status |
會話狀態 | src/agents/tools/sessions-status-tool.ts |
webSearch |
網路搜尋 | src/agents/tools/web-search-tool.ts |
webFetch |
網頁抓取 | src/agents/tools/web-fetch-tool.ts |
type AgentTool<Input = any, Output = unknown> = {
name: string;
description: string;
inputSchema: JSONSchema;
handler: (params: Input) => Promise<AgentToolResult>;
};用於跨頻道發送訊息：
// 支援的操作
type MessageToolAction =
| "send" // 發送訊息
| "reply" // 回覆訊息
| "thread-reply" // 線程回覆
| "sendAttachment" // 發送附件
| "react" // 添加反應
| "fetch" // 獲取訊息歷史
| "edit" // 編輯訊息
| "delete"; // 刪除訊息用於生成子 Agent：
// Agent 內呼叫
const result = await tool.spawn({
agentId: "research-agent",
prompt: "研究主題 X",
model: "anthropic/claude-3-opus",
thinking: "extended"
});主配置檔：~/.openclaw/config.json5
{
// Agent 配置
"agents": {
"defaults": {
"model": "anthropic/claude-3-5-sonnet",
"workspace": "~"
},
"list": [/* Agent 列表 */]
},
// 頻道配置
"channels": {
"telegram": {
"botToken": "xxx",
"allowFrom": [123456789]
},
"discord": {
"accounts": {
"main": {
"token": "xxx",
"guilds": { "allow": ["guild-id"] }
}
}
}
},
// 路由綁定
"bindings": [/* 綁定規則 */],
// 會話配置
"session": {
"dmScope": "per-peer",
"identityLinks": {}
},
// 模型配置
"models": {
"providers": {/* Provider 配置 */}
},
// Gateway 配置
"gateway": {
"mode": "local",
"port": 18789
}
}使用 Zod schema 驗證：
src/config/zod-schema.ts- 定義驗證規則- 啟動時自動驗證
- 熱重載時重新驗證
支援在配置中引用環境變數：
{
"channels": {
"telegram": {
"botToken": "${TELEGRAM_BOT_TOKEN}"
}
}
}{
// 元資料（自動生成）
"meta": {
"lastTouchedVersion": "2025.2.6",
"lastTouchedAt": "2025-02-06T10:30:00.000Z"
},
// 環境變數配置
"env": {
"shellEnv": {
"enabled": false,
"timeoutMs": 15000
},
"vars": {
"CUSTOM_VAR": "value"
}
},
// Agent 配置
"agents": {
"defaults": {
"workspace": "/path/to/workspace",
"model": {
"primary": "anthropic/claude-3-5-sonnet",
"fallbacks": ["openai/gpt-4"]
},
"memorySearch": { "enabled": true }
},
"list": [
{
"id": "main",
"default": true,
"name": "主要助手"
},
{
"id": "code-agent",
"workspace": "/path/to/code",
"skills": ["code_execution"]
}
]
},
// 綁定規則
"bindings": [
{
"agentId": "code-agent",
"match": {
"channel": "telegram",
"peer": { "kind": "group", "id": "-100xxx" }
}
}
],
// Gateway 設定
"gateway": {
"mode": "local",
"port": 18789
},
// 頻道配置
"channels": {
"telegram": {
"botToken": "${TELEGRAM_BOT_TOKEN}",
"dmPolicy": "allowlist",
"allowFrom": [123456789]
}
},
// 工具配置
"tools": {
"profile": "full",
"web": {
"search": { "enabled": true },
"fetch": { "enabled": true }
}
},
// 會話設定
"session": {
"dmScope": "main"
}
}📁 Source:
src/config/types.ts,src/config/zod-schema.ts
1. 解析 JSON5 檔案
└─→ src/config/io.ts: loadConfig()
│
2. 處理 $include 指令（支援多檔案）
└─→ src/config/includes.ts
│
3. 套用 config.env 至 process.env
│
4. 環境變數代換 ${VAR}
└─→ src/config/env-substitution.ts
│
5. Zod Schema 驗證
└─→ src/config/validation.ts
│
6. 套用預設值
└─→ src/config/defaults.ts
│
7. 正規化路徑
└─→ src/config/normalize-paths.ts
│
8. 套用執行時覆蓋
│
▼
✓ 配置就緒
| 政策 | 說明 |
|---|---|
"pairing" |
未知使用者需配對碼 |
"allowlist" |
只允許 allowFrom 中的使用者 |
"open" |
允許所有 DM |
"disabled" |
禁用所有 DM |
| 命令 | 說明 |
|---|---|
openclaw gateway run |
啟動 Gateway |
openclaw agent --message "..." |
執行 Agent |
openclaw message send |
發送訊息 |
openclaw channels status |
頻道狀態 |
openclaw config set/get |
配置管理 |
openclaw doctor |
診斷工具 |
openclaw login |
登入 Web 服務 |
# 啟動 Gateway
openclaw gateway run --bind loopback --port 18789
# 強制重啟
openclaw gateway run --force
# 指定配置
openclaw gateway run --config /path/to/config.json5# 傳送訊息給 Agent
openclaw agent --message "你好"
# 指定 Agent
openclaw agent --agent code-agent --message "寫一個函數"
# 指定會話
openclaw agent --session "agent:main:telegram:dm:123" --message "..."# 查看頻道狀態
openclaw channels status
# 深度探測
openclaw channels status --deep
# 特定頻道
openclaw channels status telegram# 查看配置
openclaw config get agents.defaults.model
# 設定配置
openclaw config set agents.defaults.model anthropic/claude-3-opus
# 列出所有配置
openclaw config list| 類型 | 大小限制 |
|---|---|
| 圖片 | 6 MB |
| 音訊 | 16 MB |
| 影片 | 16 MB |
| 文件 | 100 MB |
- 位置：
~/.openclaw/media/ - 格式：
{sanitized-name}---{uuid}.{ext} - TTL：2 分鐘（自動清理）
多層檢測策略：
- Buffer sniffing（魔術數字）
- 副檔名推斷
- HTTP Content-Type header
- 後端：Sharp 或 sips（macOS）
- 功能：
- EXIF 方向自動修正
- HEIC → JPEG 轉換
- PNG/JPEG 自適應壓縮
支援的服務：
- ElevenLabs
- OpenAI TTS
- Edge TTS
模式：
auto- 自動判斷always- 總是語音inbound- 收到語音時回語音tagged- 標記時才語音
三種模式：
| 政策 | 說明 |
|---|---|
open |
允許所有人 DM |
pairing |
需要配對碼 |
allowlist |
僅允許清單內的使用者 |
{
"channels": {
"telegram": {
"allowFrom": [
123456789, // 使用者 ID
-100123456789 // 群組 ID
]
}
}
}- 位置：
~/.openclaw/auth-profiles/ - 支援多個 API key 輪替
- 自動處理 rate limit
{
"agents": {
"list": [{
"id": "untrusted-agent",
"sandbox": {
"enabled": true,
"allowedPaths": ["/tmp/sandbox"]
}
}]
}
}{
"agents": {
"list": [{
"id": "untrusted-agent",
"sandbox": {
"mode": "all", // off | non-main | all
"scope": "session", // session | agent | shared
"workspaceAccess": "ro", // none | ro | rw
"tools": {
"deny": ["bash_exec", "file_write"]
}
}
}]
}
}| 模式 | 說明 | 安全級別 |
|---|---|---|
off |
無沙箱 | 🔴 最低 |
non-main |
非主 Agent 使用沙箱 | 🟡 中等 |
all |
所有 Agent 使用沙箱 | 🟢 高 |
📁 Source:
src/config/types.ts(SandboxConfig)
# 基本審計
openclaw security audit
# 深度審計（含 Gateway 探測）
openclaw security audit --deep
# 自動修復權限問題
openclaw security audit --fix- 永遠使用 allowlist：不要用
dmPolicy: "open" - 隔離會話：設定
session.dmScope: "per-channel-peer" - 保護配置檔：
chmod 600 ~/.openclaw/config.json5 - Gateway 認證：暴露於網路時設定 token
- 沙箱不信任模型：小型/未知模型使用沙箱
| 事件類型 | 觸發點 | 用途 |
|---|---|---|
command:new |
/new 命令 |
會話重置前執行 |
command:reset |
/reset 命令 |
會話重置前執行 |
command:stop |
/stop 命令 |
停止前執行 |
agent:bootstrap |
Agent 啟動 | 注入 bootstrap 檔案前 |
gateway:startup |
Gateway 就緒 | 初始化任務 |
📁 Source:
src/hooks/types.ts,src/hooks/internal-hooks.ts
my-hook/
├── HOOK.md # 元數據 + 文檔（必須）
└── handler.ts # 實現（必須）
---
name: my-hook
description: "Hook 描述"
metadata:
{
"openclaw": {
"emoji": "🎯",
"events": ["command:new", "command:reset"],
"export": "default",
"requires": {
"bins": ["node"],
"env": ["MY_VAR"]
}
}
}
enabled: true
---- Workspace Hooks（最高）：
<workspace>/hooks/ - Managed Hooks：
~/.openclaw/hooks/ - Bundled Hooks：OpenClaw 內建
- Extra Dirs：配置中指定的額外目錄
| Hook | 事件 | 功能 |
|---|---|---|
session-memory |
command:new |
保存會話摘要到記憶 |
command-logger |
command |
記錄所有命令到日誌 |
soul-evil |
agent:bootstrap |
根據配置替換 SOUL.md |
boot-md |
gateway:startup |
執行 BOOT.md 任務 |
{
"hooks": {
"internal": {
"enabled": true,
"entries": {
"session-memory": {
"enabled": true,
"messages": 25 // 保存最近 N 條訊息
}
},
"load": {
"extraDirs": ["/path/to/custom/hooks"]
}
}
}
}# 列出 hooks
openclaw hooks list
openclaw hooks list --eligible # 只顯示符合條件的
# Hook 資訊
openclaw hooks info session-memory
# 啟用/禁用
openclaw hooks enable session-memory
openclaw hooks disable command-logger
# 安裝 hook pack
openclaw hooks install @acme/my-hooks📁 Source:
src/hooks/loader.ts,src/cli/hooks-cli.ts
插件位於 extensions/ 目錄，每個插件是獨立的 npm package。
| 擴展 | 說明 |
|---|---|
matrix |
Matrix 協定 |
msteams |
Microsoft Teams |
feishu |
飛書/Lark |
line |
LINE Messaging |
bluebubbles |
BlueBubbles |
mattermost |
Mattermost |
voice-call |
語音通話 |
- 建立
extensions/{name}/目錄 - 初始化
package.json - 實作
src/channel.ts - 匯出
ChannelPlugin
| 級別 | 說明 |
|---|---|
silent |
完全關閉 |
fatal |
致命錯誤 |
error |
錯誤 |
warn |
警告 |
info |
一般資訊（預設） |
debug |
除錯資訊 |
trace |
最詳細追蹤 |
{
"logging": {
"level": "info", // 檔案日誌級別
"file": "/tmp/openclaw/openclaw-YYYY-MM-DD.log",
"consoleLevel": "info", // 控制台級別
"consoleStyle": "pretty", // pretty | compact | json
"redactSensitive": "tools" // off | tools（自動清理敏感資訊）
}
}# 即時尾部（推薦）
openclaw logs --follow
# JSON 格式
openclaw logs --follow --json
# 頻道特定日誌
openclaw channels logs --channel whatsapp# 基本健康檢查
openclaw health
# 詳細檢查
openclaw health --verbose
# JSON 輸出
openclaw health --json# 本地摘要
openclaw status
# 完整診斷
openclaw status --all
# 同時探測 Gateway
openclaw status --deep
# 使用量報告
openclaw status --usage自動清理的模式：
- API Keys：
sk-***,ghp_***,npm_*** - 環境變數：
API_KEY=*** - Authorization headers：
Bearer *** - PEM 私鑰塊
📁 Source:
src/logging/redact.ts,src/logging/console.ts
# 互動式診斷
openclaw doctor
# 自動修復
openclaw doctor --fix
# 非互動模式
openclaw doctor --non-interactiveDoctor 檢查項目包括：
- 配置驗證
- Gateway 連接
- 頻道狀態
- 安全審計
- 工作區完整性
npm 全域安裝：
npm install -g openclawDocker：
docker run -v ~/.openclaw:/root/.openclaw openclaw/openclawmacOS App： 從官網下載 DMG 安裝
- Node.js 22+
- 記憶體：建議 4GB+
- 磁碟：建議 1GB+（含媒體快取）
| 模式 | 說明 |
|---|---|
| 本地 | 在個人電腦運行 |
| Docker | 容器化部署 |
| Fly.io | 雲端部署 |
| Render | 雲端部署 |
- Menubar App：狀態列圖示
- LaunchAgent：開機自動啟動
- 快捷鍵：全域快捷鍵支援
| 用途 | 檔案路徑 |
|---|---|
| 程式進入點 | src/entry.ts |
| Gateway 實作 | src/gateway/server.impl.ts |
| Agent 執行 | src/agents/pi-embedded-runner/run.ts |
| 頻道 Adapter | src/channels/plugins/types.adapters.ts |
| 路由解析 | src/routing/resolve-route.ts |
| 工具定義 | src/agents/openclaw-tools.ts |
| 配置類型 | src/config/types.ts |
| 配置驗證 | src/config/zod-schema.ts |
| 自動回覆 | src/auto-reply/dispatch.ts |
| 記憶系統 | src/memory/ |
| 媒體處理 | src/media/ |
本文檔基於 OpenClaw 源碼分析產生，最後更新：2026-02-06