
一、配置文件基礎
1.1 配置文件位置
OpenClaw 的配置文件主要位于用戶主目錄的 .openclaw 文件夾中:
bash
# 主配置文件
~/.openclaw/openclaw.json
# 審批配置文件(自動生成)
~/.openclaw/exec-approvals.json
# 工作目錄
~/.openclaw/workspace/
1.2 配置文件結構
主配置文件 openclaw.json 采用 JSON 格式,包含以下主要部分:
Json
{
"meta": {
"lastTouchedVersion": "2026.3.23-2",
"lastTouchedAt": "2026-04-02T08:20:51.104Z"
},
"agents": {
"defaults": {
"model": {
"primary": "zai/glm-5",
"fallbacks": [...]
},
"workspace": "/home/ubuntu/.openclaw/workspace"
}
},
"channels": {
"feishu": {
"enabled": true,
"appId": "...",
"appSecret": "..."
}
},
"gateway": {
"port": 18789,
"mode": "local",
"bind": "loopback"
},
"plugins": {
"entries": {
"feishu": {
"enabled": true
}
}
}
}
二、核心配置詳解
2.1 Agents 配置
Agents 是 OpenClaw 的核心組件,負責處理用戶請求和響應。
2.1.1 基本配置
Json
"agents": {
"defaults": {
"model": {
"primary": "zai/glm-5",
"fallbacks": [
"qwen-portal/coder-model",
"qwen-portal/vision-model",
"custom-api-deepseek-com/deepseek-chat"
]
},
"models": {
"qwen-portal/coder-model": {
"alias": "qwen"
},
"zai/glm-5": {
"alias": "GLM"
}
},
"workspace": "/home/ubuntu/.openclaw/workspace",
"compaction": {
"mode": "safeguard"
}
}
}
2.1.2 模型配置
OpenClaw 支持多種模型提供商:
Json
"models": {
"mode": "merge",
"providers": {
"zai": {
"baseUrl": "https://open.bigmodel.cn/api/paas/v4",
"api": "openai-compat",
"models": [
{
"id": "glm-5",
"name": "GLM-5",
"reasoning": true,
"cost": {
"input": 1,
"output": 3.2
}
}
]
},
"custom-api-deepseek-com": {
"baseUrl": "https://api.deepseek.com/v1",
"apiKey": "sk-your-api-key",
"api": "openai-compat",
"models": [
{
"id": "deepseek-chat",
"name": "deepseek-chat (Custom Provider)"
}
]
}
}
}
2.2 Channels 配置
Channels 定義了 OpenClaw 支持的通信渠道。
2.2.1 飛書配置
Json
"channels": {
"feishu": {
"enabled": true,
"appId": "...",
"appSecret": "...",
"connectionMode": "websocket",
"domain": "feishu",
"groupPolicy": "disabled"
}
}
2.2.2 WebChat 配置
Json
"channels": {
"webchat": {
"enabled": true,
"port": 18789
}
}
2.3 Bindings 配置
Bindings 將 Agents 與 Channels 綁定:
Json
"bindings": [
{
"agentId": "main",
"match": {
"channel": "feishu",
"accountId": "default"
}
},
{
"agentId": "main",
"match": {
"channel": "webchat",
"accountId": "default"
}
}
]
2.4 Gateway 配置
Gateway 是 OpenClaw 的核心服務組件:
Json
"gateway": {
"port": 18789,
"mode": "local",
"bind": "loopback",
"controlUi": {
"allowedOrigins": [
"http://localhost:18789",
"http://127.0.0.1:18789"
]
},
"auth": {
"mode": "token",
"token": "..."
},
"tailscale": {
"mode": "off",
"resetOnExit": false
},
"nodes": {
"denyCommands": [
"camera.snap",
"camera.clip",
"screen.record",
"contacts.add",
"calendar.add",
"reminders.add",
"sms.send"
]
}
}
2.5 Plugins 配置
Plugins 擴展 OpenClaw 的功能:
Json
"plugins": {
"allow": [
"feishu",
"qwen-portal-auth"
],
"load": {
"paths": [
"/home/ubuntu/.npm-global/lib/node_modules/openclaw/dist/extensions/feishu"
]
},
"entries": {
"feishu": {
"enabled": true
},
"qwen-portal-auth": {
"enabled": true
}
}
}
三、審批配置管理
3.1 審批配置概述
審批配置通過 openclaw approvals 命令管理,而不是手動編輯配置文件。
3.2 基本命令
3.2.1 查看當前審批配置
bash
# 查看本地審批配置
openclaw approvals get
# 查看 Gateway 的審批配置
openclaw approvals get --gateway
# 查看特定節(jié)點的審批配置
openclaw approvals get --node <node-id>
3.2.2 管理白名單
bash
添加到白名單
# 添加單個命令(所有代理)
openclaw approvals allowlist add "/usr/bin/ls"
# 添加到特定代理
openclaw approvals allowlist add --agent "main" "/usr/bin/cat"
# 添加到所有代理
openclaw approvals allowlist add --agent "*" "/usr/bin/echo"
# 添加通配符模式
openclaw approvals allowlist add "/usr/bin/*"
openclaw approvals allowlist add "/home/user/scripts/*"
從白名單移除
bash
# 移除單個命令
openclaw approvals allowlist remove "/usr/bin/ls"
# 移除特定代理的命令
openclaw approvals allowlist remove --agent "main" "/usr/bin/cat"
3.3 實際使用示例
3.3.1 添加常用安全命令
bash
# 添加基礎文件操作命令
openclaw approvals allowlist add --agent "*" "/usr/bin/ls"
openclaw approvals allowlist add --agent "*" "/usr/bin/cat"
openclaw approvals allowlist add --agent "*" "/usr/bin/head"
openclaw approvals allowlist add --agent "*" "/usr/bin/tail"
openclaw approvals allowlist add --agent "*" "/usr/bin/grep"
openclaw approvals allowlist add --agent "*" "/usr/bin/find"
openclaw approvals allowlist add --agent "*" "/usr/bin/wc"
openclaw approvals allowlist add --agent "*" "/usr/bin/echo"
openclaw approvals allowlist add --agent "*" "/usr/bin/pwd"
openclaw approvals allowlist add --agent "*" "/usr/bin/which"
openclaw approvals allowlist add --agent "*" "/usr/bin/whoami"
# 添加網(wǎng)絡命令
openclaw approvals allowlist add --agent "*" "/usr/bin/curl"
openclaw approvals allowlist add --agent "*" "/usr/bin/wget"
# 添加系統(tǒng)信息命令
openclaw approvals allowlist add --agent "*" "/usr/bin/ps"
openclaw approvals allowlist add --agent "*" "/usr/bin/top"
openclaw approvals allowlist add --agent "*" "/usr/bin/free"
openclaw approvals allowlist add --agent "*" "/usr/bin/df"
openclaw approvals allowlist add --agent "*" "/usr/bin/du"
3.3.2 批量管理
bash
# 創(chuàng)建一個腳本批量添加
cat > add-safe-commands.sh << 'EOF'
#!/bin/bash
commands=(
"/usr/bin/ls"
"/usr/bin/cat"
"/usr/bin/head"
"/usr/bin/tail"
"/usr/bin/grep"
"/usr/bin/find"
"/usr/bin/wc"
"/usr/bin/echo"
"/usr/bin/pwd"
"/usr/bin/which"
"/usr/bin/whoami"
)
for cmd in "${commands[@]}"; do
openclaw approvals allowlist add --agent "*" "$cmd"
echo "Added: $cmd"
done
EOF
chmod +x add-safe-commands.sh
./add-safe-commands.sh
3.3.3 創(chuàng)建審批配置文件
bash
# 創(chuàng)建自定義審批配置文件
cat > my-approvals.json << 'EOF'
{
"version": 1,
"defaults": {
"security": "allowlist"
},
"agents": {
"main": {
"allowlist": [
"/usr/bin/*",
"/bin/*",
"/usr/local/bin/*",
"/home/user/scripts/*"
]
},
"subagent": {
"allowlist": [
"/usr/bin/ls",
"/usr/bin/cat",
"/usr/bin/grep"
]
}
}
}
EOF
# 應用配置
openclaw approvals set --file my-approvals.json
3.4 高級選項
3.4.1 目標選項
bash
# 目標類型
--local # 本地(默認)
--gateway # Gateway
--node <id> # 特定節(jié)點
# 代理選項
--agent "*" # 所有代理(默認)
--agent "main" # 特定代理
--agent "subagent" # 另一個代理
3.4.2 詳細輸出
bash
# 詳細模式
openclaw approvals get --verbose
# JSON 輸出
openclaw approvals get --json
# 格式化輸出
openclaw approvals get --format pretty
四、常見配置場景
4.1 開發(fā)環(huán)境 配置
{
"agents": {
"defaults": {
"model": {
"primary": "zai/glm-5",
"fallbacks": ["qwen-portal/coder-model"]
}
}
},
"channels": {
"feishu": {
"enabled": true,
"groupPolicy": "allowlist"
},
"webchat": {
"enabled": true
}
}
}
# 開發(fā)環(huán)境:允許更多命令
openclaw approvals allowlist add --agent "*" "/usr/bin/git"
openclaw approvals allowlist add --agent "*" "/usr/bin/npm"
openclaw approvals allowlist add --agent "*" "/usr/bin/docker"
openclaw approvals allowlist add --agent "*" "/usr/bin/vim"
openclaw approvals allowlist add --agent "*" "/usr/bin/nano"
4.2 生產環(huán)境配置
{
"gateway": {
"mode": "remote",
"bind": "any"
},
"channels": {
"feishu": {
"enabled": true,
"groupPolicy": "disabled"
}
},
"plugins": {
"entries": {
"feishu": {
"enabled": true
}
}
}
}
# 生產環(huán)境:只允許必要命令
openclaw approvals allowlist add --agent "*" "/usr/bin/ls"
openclaw approvals allowlist add --agent "*" "/usr/bin/cat"
openclaw approvals allowlist add --agent "*" "/usr/bin/grep"
openclaw approvals allowlist add --agent "*" "/usr/bin/ps"
4.3 多代理配置
{
"agents": {
"main": {
"model": "zai/glm-5",
"thinking": "high"
},
"coder": {
"model": "custom-api-deepseek-com/deepseek-chat",
"thinking": "medium"
},
"assistant": {
"model": "qwen-portal/coder-model",
"thinking": "low"
}
},
"bindings": [
{
"agentId": "main",
"match": {
"channel": "feishu",
"accountId": "default"
}
},
{
"agentId": "coder",
"match": {
"channel": "webchat",
"accountId": "coding"
}
}
]
}
五、配置管理最佳實踐
5.1 配置文件管理
bash
# 備份配置文件
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup
# 查看配置文件差異
diff ~/.openclaw/openclaw.json.backup ~/.openclaw/openclaw.json
# 修復配置錯誤
openclaw doctor --fix
5.2 安全配置
bash
# 限制敏感命令
openclaw approvals allowlist remove --agent "*" "/usr/bin/rm"
openclaw approvals allowlist remove --agent "*" "/usr/bin/mv"
openclaw approvals allowlist remove --agent "*" "/usr/bin/cp"
# 只允許特定目錄的命令
openclaw approvals allowlist add --agent "*" "/usr/bin/ls /home/user"
openclaw approvals allowlist add --agent "*" "/usr/bin/cat /etc/hosts"
5.3 監(jiān)控和維護
bash
# 定期備份審批配置
openclaw approvals get > approvals-backup-$(date +%Y%m%d).json
# 檢查最近使用的命令
openclaw approvals get --verbose | grep "Last Used"
# 驗證配置完整性
openclaw status
六、故障排除
6.1 常見問題
6.1.1 配置錯誤
bash
# 檢查配置語法
python3 -m json.tool ~/.openclaw/openclaw.json
# 修復配置
openclaw doctor --fix
6.1.2 插件 加載失敗
bash
# 檢查插件狀態(tài)
openclaw plugins list
# 重新加載插件
openclaw gateway restart
一鍵獲取完整項目代碼
6.1.3 審批配置問題
# 重置審批配置
openclaw approvals set --file /dev/null
# 重新添加必要命令
openclaw approvals allowlist add --agent "*" "/usr/bin/ls"
openclaw approvals allowlist add --agent "*" "/usr/bin/cat"
6.2 調試技巧
bash
# 啟用詳細日志
export OPENCLAW_LOG_LEVEL=debug
openclaw gateway start
# 查看日志
tail -f ~/.openclaw/logs/gateway.log
# 測試配置
openclaw config test