附录 B：配置参考

OpenClaw 的核心配置在 openclaw.json 中。以下是最常用的字段说明。

配置文件默认路径：

系统	路径
macOS	~/.openclaw/openclaw.json
Linux	~/.openclaw/openclaw.json
Windows	%USERPROFILE%\.openclaw\openclaw.json

---

📦 顶层字段

{
  "gateway": { /* Gateway 配置 */ },
  "agents": { /* Agent 配置 */ },
  "channels": { /* 通道配置 */ },
  "models": { /* 模型配置 */ },
  "tools": { /* 工具配置 */ },
  "auth": { /* 认证配置 */ },
  "session": { /* 会话配置 */ },
  "plugins": { /* 插件配置 */ }
}

🌐 Gateway 配置

{
  "gateway": {
    "mode": "local",           // 模式：local | remote | edge
    "port": 18789,             // 端口，默认 18789
    "bind": "loopback",        // 绑定：loopback | lan | tailnet | auto
    "auth": {
      "mode": "token",         // 认证：none | token | password | trusted-proxy
      "token": "你的令牌"       // mode 为 token 时必填
    },
    "tailscale": {
      "mode": "off",           // Tailscale：off | serve | funnel
      "resetOnExit": false
    },
    "controlUi": {
      "allowInsecureAuth": true // 控制面板允许不安全认证
    }
  }
}

🤖 Agent 配置

{
  "agents": {
    "defaults": {
      "workspace": "/路径/workspace",  // 默认工作区
      "model": {
        "primary": "deepseek/deepseek-v4-flash"  // 默认模型
      }
    },
    "list": [
      {
        "id": "writer",           // Agent 唯一标识
        "name": "文案",            // 显示名称
        "description": "负责写教程",
        "workspace": "/路径/agents/writer",
        "model": {
          "primary": "deepseek/deepseek-v4-flash"
        }
      }
    ]
  }
}

关键字段：

• id：Agent 的唯一 ID，路由时用到
• workspace：工作区路径，Agent 在这读文件、写文件
• model.primary：该 Agent 使用的主模型

📡 通道配置

{
  "channels": {
    "feishu": {
      "appId": "cli_xxxxxxxxxxxx",
      "appSecret": "你的应用密钥",
      "enabled": true
    },
    "discord": {
      "token": "你的 Bot Token",
      "enabled": true
    },
    "telegram": {
      "token": "你的 Bot Token",
      "enabled": true
    }
  }
}

🧠 模型配置

{
  "models": {
    "providers": {
      "deepseek": {
        "baseUrl": "https://api.deepseek.com",
        "apiKey": "你的 API Key"
      },
      "openai": {
        "baseUrl": "https://api.openai.com/v1",
        "apiKey": "你的 OpenAI Key"
      }
    },
    "default": "deepseek/deepseek-v4-flash",
    "defaultImage": "openai/gpt-4o"
  }
}

🛠️ 工具配置

{
  "tools": {
    "profile": "coding",     // 工具配置档：basic | coding | full
    "web": {
      "search": {
        "provider": "gemini",  // 搜索提供商
        "enabled": true
      }
    },
    "exec": {
      "timeout": 30,          // 命令执行超时（秒）
      "ask": true             // 执行命令前是否确认
    }
  }
}

工具配置档 (profile) 说明：

配置档	启用工具	适用场景
basic	读文件、搜索	纯对话、查询
coding	基本 + 写文件、执行命令	写代码、写文档
full	全部工具	全功能模式

🔒 安全配置

{
  "approvals": {
    "exec": {
      "channel": "feishu",      // 审批发到哪个通道
      "maxTimeout": 300         // 审批超时（秒）
    }
  }
}

🎯 会话配置

{
  "session": {
    "dmScope": "per-channel-peer"  // 私聊会话范围
  }
}

---

📖 要查看完整的配置 schema，运行：

openclaw config schema

会输出一份完整的 JSON Schema。

修改配置后记得运行 openclaw config validate 检查格式。