配置参?

~/.openclaw/openclaw.json 中每个可用的字段。关于面向任务的概述，请参阅配置?

配置格式?JSON5（允许注释和尾随逗号）。所有字段都是可选的 —?省略?OpenClaw 使用安全默认值?

渠道

每个渠道在其配置部分存在时自动启动（除非 enabled: false）?

DM 和群组访?

所有渠道都支持 DM 策略和群组策略：

DM 策略行为
pairing（默认）未知发送者获得一次性配对码；所有者必须批?
allowlist仅允许来?allowFrom（或配对允许存储）的发送?
open允许所有入?DM（需?allowFrom: ["*"]?
disabled忽略所有入?DM
群组策略行为
allowlist（默认）仅允许匹配配置的允许列表的群?
open绕过群组允许列表（提及门控仍然适用?

渠道字段

所有渠道共享这些字段：

  • enabled：布尔值，默认 true
  • dm：DM 策略（见上文?
  • group：群组策略（见上文）
  • allowFrom：发送者白名单（见下文?
  • ignoreFrom：发送者黑名单
  • meta：可选附加到每条消息的上下文元数?

allowFrom 格式?

{
  // 特定用户
  allowFrom: ["[email protected]", "[email protected]"],

  // 或通配符（需?"open" 策略?
  allowFrom: ["*"],

  // 或特定群组（取决于渠道）
  allowFrom: ["+123456789"], // Telegram 群组 ID
  allowFrom: ["!>U123456789:TG"], // Slack 用户 ID
}

渠道特定字段

每个渠道可能有额外的特定字段。请参阅各个渠道页面获取详细信息?

模型

模型配置

{
  "models": {
    // 默认模型（必需?
    "default": "claude-sonnet-4-5",

    // 模型提供?
    "providers": {
      // Anthropic（Claude?
      "anthropic": {
        "apiKey": "sk-ant-...",
        // 或使?secret ref?
        // "apiKey": { "source": "env", "id": "ANTHROPIC_API_KEY" }
      },

      // OpenAI
      "openai": {
        "apiKey": "sk-...",
        "defaultModel": "gpt-5",
        // 可选：
        // "baseUrl": "https://api.openai.com/v1"
      },

      // Google Gemini
      "google": {
        "apiKey": "AIza...",
        "defaultModel": "gemini-2-flash"
      },

      // 其他提供?..
    }
  }
}

模型选择

在会话中切换模型?

  • 使用 /model 命令
  • 或设?session.model

模型名称格式：provider/model（例?anthropic/claude-opus-4-6、openai/gpt-5?

网关

网关基本配置

{
  "gateway": {
    // 绑定地址
    "bind": "loopback", // "loopback" | "lan" | "tailnet"

    // 端口
    "port": 18789,

    // 认证
    "auth": {
      "mode": "token", // "token" | "none" | "trusted-proxy"
      "token": "your-token-here",
      // 或使?secret ref?
      // "token": { "source": "env", "id": "OPENCLAW_GATEWAY_TOKEN" }
    }
  }
}

网关模式

  • loopback：仅本地访问（默认）
  • lan：局域网访问
  • tailnet：Tailscale 网络访问

远程网关

连接到远程网关：

{
  "gateway": {
    "remote": {
      "url": "https://your-gateway.example.com:18789",
      "token": "remote-token"
    }
  }
}

代理

代理配置

{
  "agents": {
    // 默认设置
    "defaults": {
      "model": "claude-sonnet-4-5",
      "profile": "default",

      // 沙盒设置
      "sandbox": {
        "mode": "non-main", // "off" | "non-main" | "all"
        "scope": "session", // "session" | "agent" | "shared"
        "workspaceAccess": "none" // "none" | "ro" | "rw"
      },

      // 工具策略
      "tools": {
        "profile": "default",
        "allow": [],
        "deny": []
      }
    },

    // 代理列表
    "list": [
      {
        "id": "main",
        "name": "Main Agent",
        "model": "claude-opus-4-6",
        // 覆盖默认设置...
      }
    ]
  }
}

代理 ID

  • main：主代理（默认）
  • 其他代理?agents.list 中定?

工具

工具配置

{
  "tools": {
    // 工具配置
    "profile": "default",

    // 允许的工?
    "allow": [],
    "deny": [],

    // 沙盒工具策略
    "sandbox": {
      "tools": {
        "allow": [],
        "deny": []
      }
    },

    // 提权执行
    "elevated": {
      "enabled": false,
      "allowFrom": {}
    }
  }
}

工具?

可用的工具组?

  • group:runtime：exec、bash、process
  • group:fs：read、write、edit、apply_patch
  • group:sessions：sessions_list、sessions_history、sessions_send、sessions_spawn、session_status
  • group:memory：memory_search、memory_get
  • group:ui：browser、canvas
  • group:automation：cron、gateway
  • group:messaging：message
  • group:nodes：nodes
  • group:openclaw：所有内?OpenClaw 工具

技?

技能配?

{
  "skills": {
    // 启用技?
    "enabled": true,

    // 技能列?
    "entries": [
      {
        "key": "my-skill",
        "name": "My Skill",
        "command": "/my-skill",
        "path": "/path/to/skill",
        "apiKey": { "source": "env", "id": "MY_SKILL_API_KEY" }
      }
    ]
  }
}

环境变量

内联环境变量

{
  "env": {
    // 直接设置
    "OPENROUTER_API_KEY": "sk-or-...",

    // 或使?vars 对象
    "vars": {
      "GROQ_API_KEY": "gsk-..."
    }
  }
}

Shell 环境导入

{
  "env": {
    "shellEnv": {
      "enabled": true,
      "timeoutMs": 15000
    }
  }
}

日志

日志配置

{
  "logging": {
    // 日志级别
    "level": "info", // "trace" | "debug" | "info" | "warn" | "error"

    // 文件日志
    "file": {
      "enabled": true,
      "path": "~/.openclaw/logs/openclaw.log",
      "maxSize": "10mb",
      "maxFiles": 5
    },

    // 控制台日?
    "console": {
      "enabled": true,
      "level": "info"
    },

    // 敏感数据脱敏
    "redactSensitive": true
  }
}

高级配置

自定义路?

{
  // 覆盖默认路径
  "home": "~/.openclaw",
  "workspace": "~/.openclaw/workspace",
  "config": "~/.openclaw/openclaw.json"
}

网络配置

{
  "network": {
    // 代理设置
    "proxy": {
      "enabled": false,
      "url": "http://proxy:8080"
    },

    // 超时
    "timeout": {
      "request": 60000,
      "response": 120000
    }
  }
}

安全配置

{
  "security": {
    // API 密钥加密
    "encryptApiKeys": true,

    // 凭证存储
    "credentials": {
      "store": "keychain" // "keychain" | "file"
    }
  }
}

完整示例

{
  // 渠道配置
  "channels": {
    "telegram": {
      "enabled": true,
      "dm": "pairing",
      "group": "allowlist",
      "allowFrom": ["[email protected]"]
    },
    "discord": {
      "enabled": true,
      "dm": "pairing",
      "group": "allowlist"
    }
  },

  // 模型配置
  "models": {
    "default": "claude-sonnet-4-5",
    "providers": {
      "anthropic": {
        "apiKey": { "source": "env", "id": "ANTHROPIC_API_KEY" }
      },
      "openai": {
        "apiKey": { "source": "env", "id": "OPENAI_API_KEY" }
      }
    }
  },

  // 网关配置
  "gateway": {
    "bind": "loopback",
    "port": 18789,
    "auth": {
      "mode": "token",
      "token": { "source": "env", "id": "OPENCLAW_GATEWAY_TOKEN" }
    }
  },

  // 代理配置
  "agents": {
    "defaults": {
      "model": "claude-sonnet-4-5",
      "sandbox": {
        "mode": "non-main",
        "scope": "session"
      }
    },
    "list": [
      {
        "id": "main",
        "name": "Main Agent"
      }
    ]
  },

  // 工具配置
  "tools": {
    "profile": "default",
    "elevated": {
      "enabled": false
    }
  },

  // 日志配置
  "logging": {
    "level": "info",
    "file": {
      "enabled": true
    },
    "redactSensitive": true
  }
}

相关文档