OpenClaw AI Agent 平台配置指南，涵盖配置文件详解、技能开发、多平台集成等主题

OpenClaw 是一个开源的 AI Agent 平台，将大型语言模型与多种即时通讯渠道无缝集成。本文档为进阶用户提供详细的配置指南。

一、OpenClaw 架构概览

1.1 核心架构

OpenClaw 采用分层架构设计：

• 用户层：支持 WhatsApp、Telegram、Discord、Slack、飞书等平台
• Gateway 层：WebSocket 服务网关，处理连接和消息路由
• 模型层：支持 Anthropic、OpenAI、Google、Mistral 等模型提供商

1.2 核心组件

二、配置文件详解

2.1 配置文件位置

配置文件位于 ~/.openclaw/openclaw.json，使用 JSON5 格式（支持注释和尾随逗号）。

2.2 配置热重载

OpenClaw 支持配置热重载：

{  gateway: {    reload: {      mode: "hybrid",      debounceMs: 300,    },  },}

2.3 Agent 默认配置

{  agents: {    defaults: {      workspace: "~/.openclaw/workspace",      model: {        primary: "anthropic/claude-sonnet-4-5",        fallbacks: ["openai/gpt-5.2"],      },      heartbeat: {        every: "30m",        target: "last",      },    },  },}

2.4 模型提供商配置

{  models: {    providers: {      anthropic: {        apiKey: { source: "env", id: "ANTHROPIC_API_KEY" },      },      openai: {        apiKey: "${OPENAI_API_KEY}",      },    },  },}

三、Channel 集成配置

3.1 访问策略

3.2 Telegram 配置

{  channels: {    telegram: {      enabled: true,      botToken: "your-bot-token",      dmPolicy: "pairing",      groups: {        "*": { requireMention: true },      },    },  },}

3.3 Discord 配置

{  channels: {    discord: {      enabled: true,      token: "your-bot-token",      guilds: {        "123456789": {          requireMention: false,        },      },    },  },}

3.4 飞书配置

{  channels: {    feishu: {      enabled: true,      appId: "cli_xxxxx",      appSecret: { source: "env", id: "FEISHU_APP_SECRET" },    },  },}

四、Skill 技能开发

4.1 SKILL.md 格式

---name: my-skilldescription: My custom skillmetadata:  {    "openclaw":      {        "emoji": "🛠️",        "requires": { "bins": ["curl"], "env": ["API_KEY"] },      },  }---# My Skill使用说明...

4.2 技能配置

{  skills: {    entries: {      "my-skill": {        enabled: true,        apiKey: { source: "env", id: "MY_API_KEY" },      },    },  },}

五、MCP 与 ACP 集成

5.1 MCP 服务器配置

{  mcpServers: {    filesystem: {      command: "npx",      args: ["-y", "@modelcontextprotocol/server-filesystem", "~/.openclaw/workspace"],    },  },}

5.2 ACP 桥接

openclaw acpopenclaw acp --url wss://gateway.example.com:18789

六、多 Agent 配置

{  agents: {    list: [      { id: "main", default: true, workspace: "~/.openclaw/workspace" },      { id: "work", workspace: "~/.openclaw/workspace-work" },    ],  },  bindings: [    { agentId: "main", match: { channel: "telegram" } },    { agentId: "work", match: { channel: "slack" } },  ],}

七、CLI 命令参考

7.1 配置命令

openclaw onboard              # 交互式设置向导openclaw config get <path>    # 获取配置值openclaw config set <path> <value>  # 设置配置值

7.2 Gateway 命令

openclaw gateway start|stop|restart|status

7.3 诊断命令

openclaw doctor               # 健康检查openclaw doctor --deep        # 深度诊断openclaw doctor --fix         # 自动修复openclaw status --deep        # 查看状态openclaw logs --follow        # 查看日志

7.4 Channel 命令

openclaw channels add --channel telegram --account mybotopenclaw channels listopenclaw channels status

7.5 Skill 命令

openclaw skills listopenclaw skills info <name>openclaw skills check

八、故障排查

8.1 Gateway 无法启动

• 检查端口占用：lsof -i :18789
• 验证配置：openclaw config validate
• 查看日志：openclaw logs

8.2 Channel 连接失败

• 检查令牌有效性
• 验证白名单设置
• 检查网络连接

8.3 模型调用失败

• 验证 API 密钥：openclaw models status --probe
• 检查配额限制

九、资源链接

• 官网：https://openclaw.ai^[1]
• GitHub：https://github.com/openclaw/openclaw^[2]
• 文档：https://docs.openclaw.ai^[3]
• SkillHub：https://clawhub.com^[4]

引用链接