OpenClaw 的配置文件怎么写？openclaw.json 核心字段全说明

OpenClaw是一款开源个人 AI 代理工具，它将 Claude 等大模型与系统级工具链结合，支持通过 WhatsApp、Telegram、Discord 等聊天软件直接交互，并具备读写文件、浏览器自动化、邮件管理、代码执行等强大能力。它的灵活性很大程度上依赖于核心配置文件 openclaw.json。正确编写这个文件，能让你自定义模型、聊天渠道、代理行为、思考深度等，几乎所有高级功能都从这里开始。

本文将详细拆解 openclaw.json 的结构与每个核心字段的含义、用法、常见配置示例，并提供完整参考模板，帮助你从零到一掌握 OpenClaw 的配置方式。无论你是新手还是想深度定制，这份指南都能让你快速上手。

openclaw.json 文件位置与基本操作

OpenClaw 默认将配置文件放在用户主目录下的隐藏文件夹：

• Linux/macOS：~/.openclaw/openclaw.json
• Windows (WSL)：/home/<username>/.openclaw/openclaw.json
• Root 部署（不推荐）：有时出现在 /root/.openclaw/openclaw.json

还有一个 credentials 子目录存放敏感信息（如 API Key 的加密存储），主配置文件只引用它们。

如何安全编辑

1. 使用 nano、vim 或 VS Code 等编辑器：
   bash

nano ~/.openclaw/openclaw.json
2. 修改后保存，必须重启服务才能生效：
   bash

systemctl --user restart openclaw-gateway.service

# 或

openclaw gateway restart
3. 修改前强烈建议备份：
   bash

cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak

openclaw.json 整体结构概览

一个典型的 openclaw.json 包含以下顶级字段（部分字段可选）：

{
  "models": { ... },
  "channels": { ... },
  "agents": { ... },
  "skills": { ... },
  "hooks": { ... },
  "memory": { ... },
  "security": { ... },
  "gateway": { ... }
}

下面按重要性逐一拆解。

1. models：大模型配置（最核心）

models 字段定义 OpenClaw使用哪些大语言模型、API 地址、密钥、上下文窗口等。

基本结构

"models": {
  "mode": "merge | fallback | single",
  "providers": {
    "anthropic": { ... },
    "openai": { ... },
    "custom-provider": { ... }
  }
}

核心子字段说明表

官方 Anthropic 配置示例

"models": {
  "providers": {
    "anthropic": {
      "apiKey": "sk-ant-xxxxxx"
    }
  }
}

第三方/国产模型示例（MiniMax）

"providers": {
  "minimax": {
    "baseUrl": "https://api.minimax.chat/v1",
    "apiKey": "your-minimax-key",
    "api": "openai",
    "models": [
      {
        "id": "minimax-m2.1",
        "name": "MiniMax M2.1",
        "contextWindow": 131072
      }
    ]
  }
}

2. channels：聊天渠道配置

定义 OpenClaw 通过哪些即时通讯软件与你交互，支持多渠道同时开启。

常见渠道字段表

多渠道同时开启示例

"channels": {
  "telegram": {
    "enabled": true,
    "botToken": "7123456789:AAF...",
    "profiles": ["default"]
  },
  "whatsapp": {
    "enabled": true
  },
  "discord": {
    "enabled": true,
    "botToken": "MT..."
  }
}

3. agents：代理行为与默认模型

agents 定义不同场景下的 AI 行为主体，默认配置适用于所有渠道。

核心字段说明

示例：高思考深度 + 主动提醒

"agents": {
  "defaults": {
    "model": {
      "primary": "anthropic/claude-opus-4-5-20251101",
      "fallback": "anthropic/claude-3-5-sonnet-20241022"
    },
    "thinking": "high",
    "proactive": true
  }
}

4. skills 与 hooks：扩展能力

• skills：安装的工具包（如 browser、shell、email、calendar）
  json

"skills": {

"enabled": ["browser", "shell", "email", "calendar", "code"]

}
• hooks：事件触发器（如定时任务、关键词响应）

5. memory 与 security：记忆与安全

• memory：控制长期记忆存储方式（默认 Markdown 文件）
• security：权限白名单、沙箱模式等（强烈建议配置）

"security": {
  "sandbox": true,
  "allowedPaths": ["/home/user/Documents", "/home/user/Downloads"]
}

完整参考模板（Anthropic + Telegram）

{
  "models": {
    "providers": {
      "anthropic": {
        "apiKey": "sk-ant-xxxxxx"
      }
    }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "7123456789:AAF...",
      "profiles": ["default"]
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-3-5-sonnet-20241022"
      },
      "thinking": "high",
      "proactive": true
    }
  },
  "skills": {
    "enabled": ["browser", "shell", "email", "calendar"]
  },
  "security": {
    "sandbox": true
  }
}

配置后的验证与常见问题

1. 运行诊断：
   bash

openclaw doctor
2. 查看服务状态：
   bash

systemctl --user status openclaw-gateway
3. 常见错误：
4. 修改配置后未重启 → 服务不生效
5. API Key 格式错误 → 模型连接失败
6. channels 未配对 → 收不到消息（需执行 pairing approve）

结语：掌握 openclaw.json，解锁 OpenClaw 全部潜力

openclaw.json 是 OpenClaw 的灵魂所在。通过本文的字段详解、表格对比和完整示例，你已经可以灵活配置从模型到渠道、从思考深度到安全权限的方方面面。合理编写这份配置文件，能让 OpenClaw 从一个聊天机器人变成真正懂你、主动帮你处理事务的个人 AI 助理。

每次重大修改后备份文件，先在测试环境验证，再部署到主力设备。玩得开心，玩得安全！

延展阅读：

抖音dou+会影响自然流量吗？如何正确使用dou+？Dou+投放有5大黄金法则

抖音dou+投多长时间效果最好？什么时间段适合投放？抖音Dou+投放攻略：最佳时长与黄金时间段全解析

抖音dou+投放的技巧是什么？投放多少dou+能上热门？抖音DOU+投放终极指南：500元就能上热门的核心技巧