OpenClaw配置详解：openclaw.json完全指南与最佳实践

周五晚上十点，我盯着终端里刚刚跑起来的OpenClaw服务，心里松了一口气。然后打开~/.openclaw/openclaw.json，看着满屏幕的配置参数——gateway、channel、skills、provider……每个字段下面还有一堆嵌套的选项。

说实话，那一刻我有点懵。

虽然安装过程挺顺利，但面对这个配置文件，我突然意识到：自己其实不太清楚这些参数到底是干什么的。dmPolicy应该设成pairing还是allowlist？gateway.auth.token是不是就是密码？技能要全部启用吗？

Vultr - 高性能 NVMe 云服务器，32 个全球节点可选，支持一键部署 Docker

查看定价 →推广

更让人在意的是，2026年1月底OpenClaw刚修复了一个严重的安全漏洞（CVE-2026-25253，CVSS评分8.8），攻击者可以通过URL参数窃取认证token，进而执行任意命令。配置不当的话，你的AI助手可能变成别人的后门。

这篇文章就是当时的我最想看到的那份指南。我会系统性地拆解openclaw.json的所有配置模块，告诉你每个参数是什么意思、为什么需要它、以及生产环境下应该怎么设置。还会分享一些我踩过的坑和安全配置的检查清单。

配置文件的基础认知

文件在哪里，长什么样

OpenClaw的配置文件默认保存在~/.openclaw/openclaw.json。如果你是通过安装向导配置的，这个文件会自动生成；如果是手动安装，可能需要自己创建。

打开它，你会看到五大模块：

• Gateway：网关服务的端口、认证、日志等设置
• Channel：通信渠道（WhatsApp、Telegram等）的配置
• Skills：技能模块的管理和权限
• Provider：AI模型提供商（Anthropic、OpenAI、本地模型等）
• Security：安全策略和访问控制

这个结构其实挺合理——Gateway管入口，Channel管通信，Skills管能力，Provider管大脑，Security管防护。

配置方式和优先级

OpenClaw支持四种配置方式：

1. 交互式向导：安装时一步步选择，适合新手
2. 直接编辑JSON：用vim或nano直接改文件，适合熟悉配置的人
3. 环境变量：适合容器化部署或临时覆盖某个参数
4. 脚本自动化：批量部署时用脚本生成配置

重点来了：这几种方式有优先级。环境变量 > 配置文件 > 默认值。

什么意思？比如你在配置文件里设置了gateway.port: 18789，但同时设置了环境变量OPENCLAW_GATEWAY_PORT=9000，最终生效的是9000。这个设计在调试时特别有用——不用改配置文件，临时设个环境变量就能测试。

2026年的版本还增加了对MCP服务器（Model Context Protocol）的支持，可以统一接入多个搜索引擎和工具。另外，openclaw doctor命令现在能自动检查配置状态，发现问题会给出修复建议。

Gateway网关配置详解

Gateway是OpenClaw的入口，负责Web界面访问和远程客户端连接。

基础配置：端口和认证

{
  "gateway": {
    "port": 18789,
    "auth": {
      "token": "your-secret-token-here"
    },
    "remote": {
      "token": "your-remote-token-here"
    }
  }
}

• port：Web界面的访问端口，默认18789。访问http://localhost:18789就能看到OpenClaw的控制面板。如果这个端口被占用，改成别的就行（比如19000）。

• auth.token：这是网关的认证令牌，等同于密码。任何人拿到这个token，就能完全控制你的OpenClaw实例。CVE-2026-25253漏洞就是因为token可以通过URL参数泄漏。

• remote.token：远程客户端（比如手机App或桌面客户端）连接时用的令牌。和auth.token分开，是为了可以单独轮换。

安全提示：2026年1月29日的版本移除了"auth: none"选项。以前你可以关闭认证方便开发，现在强制要求使用token或password。这是针对安全漏洞的硬性修复。

高级配置：日志和WebSocket

{
  "gateway": {
    "logging": {
      "redactSensitive": true
    }
  }
}

redactSensitive设为true后，日志会自动脱敏——API密钥、token等敏感信息会被替换成***。查日志排错时不用担心不小心把密钥复制到公开的issue里。

启动网关服务的命令是openclaw gateway。服务跑起来后，你会看到类似这样的输出：

[Gateway] Listening on http://localhost:18789
[Gateway] Authentication: Token-based

Channel渠道配置策略

Channel模块决定了OpenClaw能通过哪些平台和你对话。

支持的渠道类型

目前支持四种主要渠道：

1. WhatsApp：扫码配对，最常用
2. Telegram：Bot API，适合群组场景
3. Discord：适合技术社区
4. Mattermost：企业团队协作

每个渠道的配置方式不同。WhatsApp是扫码配对流程，Telegram需要Bot Token，Discord需要创建Application。

DM（私信）策略配置

这部分是很多人搞不清楚的地方。dmPolicy决定了陌生人能不能给你的AI助手发消息。

有四种模式：

1. pairing（默认模式）

{
  "channel": {
    "dmPolicy": "pairing"
  }
}

未知发送者需要先配对验证。OpenClaw会生成一个6位配对码，有效期1小时。你需要手动批准：

openclaw pairing approve whatsapp ABC123

这个模式平衡了安全性和可用性——朋友第一次找你的AI助手时，你审核一下，之后就畅通无阻了。

2. allowlist（白名单模式）

{
  "channel": {
    "dmPolicy": "allowlist",
    "allowFrom": [
      "+1234567890",
      "telegram:@username"
    ]
  }
}

只有白名单里的人能发消息，其他人直接被屏蔽。适合你明确知道哪些人会用的场景。

3. open（开放模式）

{
  "channel": {
    "dmPolicy": "open",
    "allowFrom": ["*"]
  }
}

任何人都能发消息。老实讲，这个模式风险很高。除非你在做公开演示或者测试，否则不推荐用。

4. disabled（禁用模式）

完全关闭私信功能，只接受群组消息。

多用户场景的会话隔离

如果你的OpenClaw服务要给多个人用（比如团队共享），会话隔离很重要：

阿里云 - 开发者上云首选，轻量服务器专享 8.5 折优惠，助力项目快速上线

领取 8.5 折优惠 →推广

{
  "channel": {
    "session": {
      "dmScope": "per-channel-peer"
    }
  }
}

这样每个人的对话历史是独立的，不会串话。

Group群组策略配置

群组配置相对简单，但有个关键设置：mentionGating（@提及门控）。

{
  "channel": {
    "groupPolicy": "mention",
    "mentionGating": true
  }
}

开启后，AI助手只会回复@它的消息，而不是监听群里的每条消息。避免变成”always-on”机器人——你懂的，那种在群里疯狂刷屏的机器人。

Skills技能模块配置

Skills是OpenClaw最有意思的部分——它决定了AI助手能做什么。

Skills基础概念

技能是模块化的能力扩展。OpenClaw自带一些内置技能，ClawHub技能商店里有700+可用技能：

• 日历管理（Google Calendar、Outlook）
• 网页浏览（browser技能）
• 文件管理（file_manager）
• 终端命令（exec技能）
• 代码执行（python、node）

技能的安装路径是~/.openclaw/skills/。优先级规则：工作区技能 > 用户技能 > 内置技能。

什么意思？如果你在项目目录里放了一个自定义的browser技能，它会覆盖全局安装的版本。这个设计让你可以针对特定项目定制能力。

技能配置与管理

每个技能都有一个SKILL.md文件，里面用YAML格式定义元数据：

---
name: google-calendar
description: Manage Google Calendar events
requirements:
  bins:
    - gcalcli
  env:
    - GOOGLE_CALENDAR_API_KEY
---

bins字段列出了依赖的二进制程序。比如这个日历技能需要gcalcli命令行工具。如果系统里没装，技能会加载失败。

三种安装方式：

1. GUI安装：在Web界面点击”Add Skill”，搜索并安装
2. CLI安装：openclaw skill install google-calendar
3. 手动安装：把技能目录复制到~/.openclaw/skills/

技能故障排查

技能加载失败是常见问题。用这个命令检查依赖：

openclaw skill check google-calendar

它会告诉你缺少哪些依赖、环境变量有没有设置、OS配置是否匹配。

如果还是有问题，查看Gateway日志：

openclaw gateway --verbose

日志会显示技能加载的详细过程，哪一步出错一目了然。

小模型场景的优化

如果你用的是小上下文窗口的本地模型（比如7B参数的量化模型），可能需要禁用部分技能来控制上下文大小。技能越多，系统提示词越长，留给对话的空间就越少。

高风险技能的限制

有些技能权限很高，需要谨慎使用：

• exec：执行任意shell命令
• browser：访问任意网页
• web_fetch：抓取外部内容
• web_search：搜索引擎查询

这些技能在恶意输入的情况下可能被滥用。如果不是必需的，建议禁用。

Provider模型提供商配置

Provider决定了OpenClaw用哪个AI大脑。

支持的AI Provider

1. Anthropic（Claude）：官方主要推荐，API稳定，安全特性完善
2. OpenAI：即将支持（GPT-4等模型）
3. 本地模型：LM Studio、Ollama等
4. OpenRouter：统一多模型访问接口，一个API Key用所有模型
5. MCP服务器：2026年新特性，支持Model Context Protocol

Provider配置参数

最简单的配置（使用Anthropic）：

{
  "provider": {
    "type": "anthropic",
    "apiKey": "sk-ant-..."
  }
}

但我建议不要把API Key直接写在配置文件里，用环境变量：

export ANTHROPIC_API_KEY="sk-ant-..."

这样配置文件可以安全地提交到版本控制，API Key不会泄漏。

本地模型配置

{
  "provider": {
    "type": "openai-compatible",
    "baseURL": "http://localhost:1234/v1",
    "modelId": "kimi-k2.5-chat"
  }
}

• baseURL：本地模型服务器地址（LM Studio默认1234端口）
• modelId：指定使用的模型名称

MCP服务器配置（新特性）

{
  "provider": {
    "mcpServers": {
      "onesearch": {
        "command": "npx",
        "args": ["-y", "@onesearch/mcp-server"]
      }
    }
  }
}

OneSearch MCP让你可以通过统一接口访问多个搜索引擎（Google、Bing、Brave等），不用给每个搜索引擎单独配API Key。

本地模型的注意事项

说实话，本地模型有它的优势——隐私、成本、离线可用。但安全特性确实比商业模型弱：

Railway - 现代化的部署平台，告别繁琐运维，让代码分钟级上线

立即开始 →推广

• 提示注入风险更高：小模型更容易被恶意输入欺骗
• 上下文窗口小：安全特性需要更多系统提示词，但小模型放不下
• 量化模型的局限：4-bit量化后，模型的指令遵循能力会下降

如果你必须用本地模型，建议：

• 严格限制技能权限
• 开启沙箱模式
• 不要在有敏感数据的机器上运行

安全配置最佳实践

安全配置永远是第一优先级。CVE-2026-25253漏洞的教训告诉我们，配置不当的后果可能很严重。

安全配置清单

基础安全（必做）

• ✅ 永不分享gateway token——就像你家钥匙，千万不能给别人
• ✅ 使用防火墙，仅暴露必要端口（18789）
• ✅ SSH使用密钥认证而非密码
• ✅ 限制Web界面访问（VPN或IP白名单）
• ✅ DM策略：优先用pairing或allowlist
• ✅ 群组策略：开启mention gating

进阶安全（强烈推荐）

• ✅ 定期轮换token（至少每季度一次）
• ✅ 开启日志敏感信息脱敏
• ✅ 限制高风险技能（exec、browser）
• ✅ 使用专用服务器（不要和主要工作机混用）

输入安全与沙箱

有一条铁律：将所有外部输入视为恶意。

链接、附件、粘贴的指令——都可能是精心构造的攻击。OpenClaw的沙箱功能（opt-in）可以隔离高风险操作：

{
  "security": {
    "sandbox": {
      "enabled": true,
      "skills": ["exec", "browser"]
    }
  }
}

这样exec和browser技能会在隔离环境中运行，即使被攻破也影响不到主系统。

Secrets管理

API密钥、token等敏感信息的管理：

1. 基础方案：用SCP传输.env文件到服务器，避免在聊天中粘贴
2. 高级方案：使用Doppler、HashiCorp Vault等专业secrets管理器

千万不要做的事情：

• ❌ 在Telegram消息里发送API Key
• ❌ 把secrets提交到Git仓库
• ❌ 在公开的issue里贴日志（可能包含token）

安全审计与维护

OpenClaw内置了安全审计命令：

# 基础检查
openclaw security audit

# 深度检查
openclaw security audit --deep

# 自动应用安全防护
openclaw security audit --fix

这个命令会检查：

• Token强度是否足够
• 端口是否暴露到公网
• 文件权限是否正确（~/.openclaw应为700，配置文件应为600）
• 高风险技能是否启用
• DM策略是否安全

本地文件权限

chmod 700 ~/.openclaw
chmod 600 ~/.openclaw/openclaw.json

这样只有你自己能读写配置文件，其他用户连看都看不到。

千万不要做的事情

• ❌ 把18789端口暴露到公网
• ❌ 在不理解风险的情况下授予shell访问
• ❌ 安装未验证来源的技能
• ❌ 使用dmPolicy: "open"而不设白名单
• ❌ 在存有主要邮箱/银行信息的机器上运行OpenClaw

实战配置案例

理论讲完了，来看几个实际场景的完整配置。

场景1：个人使用，仅WhatsApp，配对模式

{
  "gateway": {
    "port": 18789,
    "auth": {
      "token": "generate-a-strong-random-token"
    },
    "logging": {
      "redactSensitive": true
    }
  },
  "channel": {
    "type": "whatsapp",
    "dmPolicy": "pairing",
    "session": {
      "dmScope": "per-channel-peer"
    }
  },
  "skills": {
    "enabled": [
      "calendar",
      "web_search",
      "file_manager"
    ],
    "disabled": [
      "exec",
      "browser"
    ]
  },
  "provider": {
    "type": "anthropic"
  },
  "security": {
    "sandbox": {
      "enabled": true
    }
  }
}

这个配置适合普通个人用户——安全性好，功能够用，高风险技能被禁用。

场景2：团队协作，多渠道，白名单模式

{
  "gateway": {
    "port": 18789,
    "auth": {
      "token": "team-gateway-token"
    },
    "remote": {
      "token": "team-remote-token"
    }
  },
  "channel": [
    {
      "type": "telegram",
      "dmPolicy": "allowlist",
      "allowFrom": [
        "telegram:@alice",
        "telegram:@bob",
        "telegram:@carol"
      ],
      "groupPolicy": "mention",
      "mentionGating": true
    },
    {
      "type": "discord",
      "dmPolicy": "allowlist",
      "allowFrom": [
        "discord:123456789"
      ]
    }
  ],
  "skills": {
    "enabled": [
      "calendar",
      "web_search",
      "github",
      "jira"
    ]
  },
  "provider": {
    "type": "anthropic"
  }
}

多渠道配置用数组形式，每个渠道独立管理白名单。群组开启mention gating避免刷屏。

场景3：本地模型，离线使用，技能精简

{
  "gateway": {
    "port": 19000
  },
  "channel": {
    "type": "whatsapp",
    "dmPolicy": "allowlist",
    "allowFrom": ["+1234567890"]
  },
  "skills": {
    "enabled": [
      "calculator",
      "file_manager"
    ]
  },
  "provider": {
    "type": "openai-compatible",
    "baseURL": "http://localhost:1234/v1",
    "modelId": "llama-3.1-8b"
  }
}

本地模型场景下，技能尽量精简——小模型的上下文窗口装不下太多系统提示词。

常见配置错误与解决

错误1：token不匹配导致无法连接

症状：Web界面显示”Authentication failed”

Vultr - 高性能 NVMe 云服务器，32 个全球节点可选，支持一键部署 Docker

查看定价 →推广

解决：检查gateway.auth.token和你输入的token是否完全一致（注意空格、换行符）

错误2：技能依赖缺失导致加载失败

症状：日志显示”Skill ‘google-calendar’ failed to load”

解决：运行openclaw skill check google-calendar，按提示安装缺失的依赖

错误3：端口冲突导致Gateway无法启动

症状：Error: listen EADDRINUSE :::18789

解决：改用其他端口，或找到占用18789的进程并杀掉

错误4：配置文件格式错误

症状：SyntaxError: Unexpected token } in JSON

解决：用JSON验证工具检查格式，常见问题是多余的逗号或引号不匹配

故障排查命令

# 查看服务状态
openclaw status

# 健康检查
openclaw doctor

# 详细日志
openclaw gateway --verbose

结论

说了这么多，核心就三点：

第一，配置文件是OpenClaw的心脏。每个参数的含义都值得理解透彻——不是为了炫技，而是为了在出问题时能快速定位。

第二，安全配置永远是第一优先级。CVE-2026-25253漏洞证明了配置不当的风险是真实存在的。token要保密、端口要限制、DM策略要收紧、高风险技能要谨慎启用。

第三，配置不是一次性工作。随着使用场景变化、团队成员增减、新技能上线，配置需要持续优化。每隔一段时间回顾一下配置，跑一次openclaw security audit，确保一切在掌控之中。

现在，立即做三件事：

1. 运行openclaw security audit --deep检查当前配置
2. 对照本文的最佳实践清单，逐项优化你的配置
3. 把优化后的配置备份到安全的地方（但别把token一起备份了）

如果你在配置过程中遇到问题，OpenClaw社区很活跃，GitHub Discussions和Discord频道都有人帮忙。也欢迎分享你的配置经验——大家都是这样一步步摸索过来的。

14 分钟阅读 · 发布于: 2026年2月5日 · 修改于: 2026年2月5日

Easton

AI与智能