# OpenClaw Gateway 配置详解

## 配置文件位置

- 默认位置: `~/.openclaw/openclaw.json`
- 开发模式: `~/.openclaw-dev/openclaw.json`

## 根配置结构

```json5
{
  // 元数据
  "meta": {},

  // 模型提供者
  "models": {},

  // Agent 配置
  "agents": {},

  // 通道配置
  "channels": {},

  // Gateway 配置
  "gateway": {},

  // 插件配置
  "plugins": {},

  // 日志配置
  "logging": {},

  // 消息配置
  "messages": {},

  // 环境变量
  "env": {},
}
```

## gateway - Gateway 配置

### 基础配置

```json5
{
  "gateway": {
    "port": 18789,                    // WebSocket 端口
    "mode": "local",                  // 模式: local|remote
    "bind": "loopback",              // 绑定: loopback|lan|tailnet|auto|custom
    "auth": {
      "mode": "token",              // 认证模式: token|password
      "token": "your-token"         // 认证 Token
    }
  }
}
```

### 远程 Gateway

```json5
{
  "gateway": {
    "mode": "remote",
    "remote": {
      "url": "wss://gateway.example.com",
      "token": "remote-token"
    }
  }
}
```

### 绑定模式说明

| 模式 | 说明 | 认证要求 |
|------|------|----------|
| `loopback` | 仅本地访问 | 可选 |
| `lan` | 局域网访问 | 必须 |
| `tailnet` | Tailscale 网络 | 必须 |
| `auto` | 自动选择 | 取决于网络 |
| `custom` | 自定义地址 | 必须 |

## logging - 日志配置

```json5
{
  "logging": {
    "level": "info",              // 文件日志级别: trace|debug|info|warn|error
    "file": "/tmp/openclaw/openclaw.log",  // 日志文件路径
    "consoleLevel": "info",       // 控制台日志级别
    "consoleStyle": "pretty",     // 控制台样式: pretty|compact|json
    "redactSensitive": "tools",   // 敏感信息脱敏: off|tools
    "redactPatterns": [           // 自定义脱敏规则
      "sk-.*"
    ]
  }
}
```

### 日志级别

- `trace` - 最详细
- `debug` - 调试信息
- `info` - 默认
- `warn` - 警告
- `error` - 错误

## agents - Agent 配置

### 全局默认配置

```json5
{
  "agents": {
    "defaults": {
      "workspace": "~/.openclaw/workspace",      // 工作目录
      "model": {
        "primary": "deepseek/deepseek-chat"    // 默认模型
      },
      "sandbox": {
        "mode": "all",                         // 沙箱模式: off|non-main|all
        "scope": "session",                    // 沙箱范围: session|agent|shared
        "workspaceAccess": "rw"                // 工作目录访问: none|ro|rw
      },
      "groupChat": {
        "mentionPatterns": ["@openclaw"]       // 群聊触发词
      }
    }
  }
}
```

### 多 Agent 配置

```json5
{
  "agents": {
    "list": [
      {
        "id": "main",
        "name": "主 Agent",
        "workspace": "~/.openclaw/workspace",
        "model": {
          "primary": "deepseek/deepseek-chat",
          "fallbacks": ["minimax/minimax-m2.1"]
        }
      },
      {
        "id": "guardian",
        "name": "守护者",
        "workspace": "~/.openclaw/workspace-guardian"
      }
    ],
    "bindings": [
      { "agentId": "main", "match": { "channel": "telegram" } },
      { "agentId": "guardian", "match": { "channel": "whatsapp" } }
    ]
  }
}
```

## channels - 通道配置

### Telegram

```json5
{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "your-bot-token",
      "dmPolicy": "pairing",           // pairing|allowlist|open|disabled
      "allowFrom": ["tg:123456789"],   // 允许发送者列表
      "groups": {
        "*": { "requireMention": true }
      },
      "replyToMode": "first",           // off|first|all
      "linkPreview": true,
      "streamMode": "partial",          // off|partial|block
      "actions": {
        "reactions": true,
        "sendMessage": true
      }
    }
  }
}
```

### WhatsApp

```json5
{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "dmPolicy": "pairing",            // pairing|allowlist|open|disabled
      "allowFrom": ["+15555550123"],
      "groups": {
        "*": { "requireMention": true }
      },
      "textChunkLimit": 4000,
      "chunkMode": "length",
      "mediaMaxMb": 50
    }
  }
}
```

### Discord

```json5
{
  "channels": {
    "discord": {
      "enabled": true,
      "token": "your-discord-token",
      "dm": {
        "enabled": true,
        "policy": "pairing"
      },
      "replyToMode": "off",
      "historyLimit": 20,
      "actions": {
        "reactions": true,
        "messages": true
      }
    }
  }
}
```

## models - 模型配置

### DeepSeek

```json5
{
  "models": {
    "providers": {
      "deepseek": {
        "baseUrl": "https://api.deepseek.com/v1",
        "apiKey": "sk-xxx",
        "api": "openai-completions",
        "models": [
          { "id": "deepseek-chat", "name": "DeepSeek" }
        ]
      }
    }
  }
}
```

### MiniMax

```json5
{
  "models": {
    "providers": {
      "minimax": {
        "baseUrl": "https://api.minimaxi.com/v1",
        "apiKey": "sk-api-xxx",
        "models": [
          { "id": "minimax-m2.1", "name": "MiniMax M2.1" },
          { "id": "embo-01", "name": "Embodied" }
        ]
      }
    }
  }
}
```

## 配置验证

OpenClaw 使用严格的 JSON Schema 验证：

```bash
# 检查配置
openclaw doctor

# 自动修复
openclaw doctor --fix
```

### 常见验证错误

| 错误 | 解决 |
|------|------|
| Unknown key | 删除未知配置项 |
| Invalid type | 检查类型是否匹配 |
| Config invalid | 运行 `openclaw doctor --fix` |

## 配置包含 ($include)

支持拆分配置文件：

```json5
// ~/.openclaw/openclaw.json
{
  "gateway": { "port": 18789 },
  "agents": { "$include": "./agents.json5" },
  "channels": { "$include": "./channels.json5" }
}
```

## 环境变量

### 内联环境变量

```json5
{
  "env": {
    "vars": {
      "OPENROUTER_API_KEY": "sk-or-..."
    }
  }
}
```

### 环境变量引用

```json5
{
  "models": {
    "providers": {
      "custom": {
        "apiKey": "${CUSTOM_API_KEY}"
      }
    }
  }
}
```

## 敏感信息脱敏

```json5
{
  "logging": {
    "redactSensitive": "tools",
    "redactPatterns": [
      "\\bTOKEN\\b\\s*[=:]\\s*([\"']?)([^\\s\"']+)\\1",
      "/\\bsk-[A-Za-z0-9_-]{8,}\\b/gi"
    ]
  }
}
```

---

*最后更新: 2026-02-04*