【OpenClaw】OpenClaw安裝配置指南教程

一、配置文件基礎

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
最后編輯于
?著作權歸作者所有,轉載或內容合作請聯(lián)系作者
【社區(qū)內容提示】社區(qū)部分內容疑似由AI輔助生成,瀏覽時請結合常識與多方信息審慎甄別。
平臺聲明:文章內容(如有圖片或視頻亦包括在內)由作者上傳并發(fā)布,文章內容僅代表作者本人觀點,簡書系信息發(fā)布平臺,僅提供信息存儲服務。

相關閱讀更多精彩內容

友情鏈接更多精彩內容