OpenClaw 配置完整教程

大家好，我是讯享网，很高兴认识大家。这里提供最前沿的Ai技术和互联网信息。

OpenClaw 的所有设置都存储在一个 JSON 配置文件（openclaw.json）中，位于 ~/.openclaw/openclaw.json。这个文件定义了你的AI助手的方方面面：使用哪个AI模型、连接哪些聊天平台、如何认证访问、AI助手的人设和行为等。

理解配置文件结构是掌握 OpenClaw 的关键。本教程将逐一拆解每个配置模块，手把手教你完成所有配置。

不想手动编辑 JSON？使用 OpenClaw Launch 的可视化配置器，所有设置都通过图形界面完成，无需写一行 JSON。

openclaw.json 是一个标准的 JSON 文件，包含以下顶层字段：

{ "models": { … }, // AI模型提供商和API密钥 "agents": { … }, // 智能体设置（模型选择、人设、提示词） "channels": { … }, // 消息渠道（Telegram、Discord、Web Chat） "plugins": { … }, // 插件启用控制 "gateway": { … } // 网关认证和端口设置 }

下面我们逐一详解每个模块的配置方法。

定义AI模型提供商及对应的API密钥。每个提供商是一个对象，包含 apiKey 字段。

"models": { "providers": {

"openrouter": { "apiKey": "sk-or-..." }, "openai": { "apiKey": "sk-..." }, "anthropic": { "apiKey": "sk-ant-..." }, "google": { "apiKey": "AIza..." }, "deepseek": { "apiKey": "sk-..." }, "moonshot": { "apiKey": "sk-..." }

} }

定义AI助手的默认行为，包括使用的模型、人设和系统提示词。

"agents": { "defaults": {

"model": { "primary": "openrouter/anthropic/claude-sonnet-4.6" }, "persona": "你是一个友好、专业的AI助手。", "systemPrompt": "你擅长帮助用户解决各类问题..."

} }

配置消息渠道（Telegram、Discord、Web Chat），每个渠道有独立的认证和策略设置。

"channels": { "telegram": {

"enabled": true, "botToken": ":ABC-DEF...", "dmPolicy": "pairing"

}, "discord": {

"enabled": true, "botToken": "MTIz...", "dmPolicy": "open", "allowFrom": ["*"]

} }

管理渠道插件的启用状态。注意：渠道配置和插件条目必须同时启用，渠道才能工作。

"plugins": { "entries": {

"telegram": { "enabled": true }, "discord": { "enabled": true }, "web-chat": { "enabled": true }

} }

配置网关认证、端口和控制台UI。auth 必须是对象格式，不能是字符串。

"gateway": { "auth": {

"token": "你的随机UUID令牌"

}, "port": 18789, "controlUi": {

"allowInsecureAuth": true

} }

模型配置是 OpenClaw 最核心的部分 — 它决定了你的AI助手使用哪个大语言模型来回答问题。OpenClaw 支持多种模型提供商，你可以配置一个或多个提供商，随时在它们之间切换。

OpenClaw 使用「提供商前缀 + 模型名称」的格式来标识模型。这个格式非常重要，写错会导致模型无法调用。

提供商模型ID格式示例 OpenRouter openrouter/厂商/模型名 openrouter/anthropic/claude-sonnet-4.6 OpenAI openai/模型名 openai/gpt-5.2 Anthropic anthropic/模型名 anthropic/claude-opus-4.6 Google google/模型名 google/gemini-3-pro DeepSeek deepseek/模型名 deepseek/deepseek-chat Moonshot moonshot/模型名 moonshot/moonshot-v1-128k

关键规则：agents.defaults.model.primary 中的模型ID前缀必须与 models.providers 中的 key 一致。例如使用 openrouter/anthropic/claude-sonnet-4.6，那么 models.providers 中必须有 openrouter 这个 key 及其 API Key。

切换模型只需修改 agents.defaults.model.primary 的值：

// 切换到 GPT-5.2 "agents": { "defaults": {

"model": { "primary": "openrouter/openai/gpt-5.2" }

} }

// 切换到 DeepSeek V3.2 "agents": { "defaults": {

"model": { "primary": "deepseek/deepseek-chat" }

} }

// 切换到 Claude Opus 4.6 "agents": { "defaults": {

"model": { "primary": "openrouter/anthropic/claude-opus-4.6" }

} }

修改后保存文件，OpenClaw 会自动热加载新的模型配置，无需重启。

你可以同时配置多个提供商的 API Key，这样就能在不同模型之间自由切换：

"models": { "providers": {

"openrouter": { "apiKey": "sk-or-..." }, "openai": { "apiKey": "sk-..." }, "deepseek": { "apiKey": "sk-..." }

} }

配置了多个提供商后，你只需要修改 agents.defaults.model.primary 就能在它们之间切换，不需要改动其他任何配置。

以下是每个AI模型提供商的 API Key 获取方法：

API Key 是连接AI模型的「钥匙」。每个模型提供商都有独立的 API Key，管理好这些密钥对安全和成本控制至关重要。

不要将 API Key 提交到 Git — 配置文件应加入 .gitignore
定期轮换密钥 — 每 3-6 个月更换一次 API Key
设置用量限制 — 在提供商控制台设置每月消费上限，防止意外超支
使用环境变量 — 生产环境中，考虑从环境变量读取密钥
监控用量 — 定期检查各提供商的用量仪表盘

推荐方案：使用 OpenRouter 作为统一的模型网关。OpenRouter 聚合了所有主流AI模型，你只需要一个 API Key 就能访问 GPT、Claude、Gemini、DeepSeek、Kimi 等所有模型。

OpenRouter 的优势：

一个 API Key 访问所有模型，免去管理多个密钥的麻烦
统一的计费和用量监控
支持模型回退 — 当一个模型不可用时自动切换到备用模型
自带免费额度，适合入门试用

BYOK 模式允许你使用自己的 API Key，费用直接从你自己的提供商账户扣除。适合有大量使用需求或需要特定模型访问权限的用户。

在 OpenClaw Launch 上配置 BYOK 非常简单 — 进入「设置」页面，在对应提供商下填入你的 API Key 即可。填入后，所有请求将通过你自己的密钥发送。

Telegram 是最受欢迎的 OpenClaw 渠道之一。以下是完整的 Telegram 配置方法：

在 Telegram 中搜索 @BotFather，进入对话
发送 /newbot 命令创建新机器人
按提示设置机器人名称和用户名（用户名必须以 bot 结尾）
BotFather 会返回一个 Bot Token，格式如 :ABC-DEF…
将 Token 填入配置文件的 channels.telegram.botToken

"channels": { "telegram": {

"enabled": true, "botToken": ":ABCdefGHIjklMNOpqrsTUVwxyz", "dmPolicy": "pairing"

} }, "plugins": { "entries": {

"telegram": { "enabled": true }

} }

dmPolicy 控制谁可以与你的 Telegram 机器人对话。Telegram 必须使用 "pairing" 模式，原因如下：

"pairing"（推荐） — 用户必须通过网关配对后才能使用机器人。防止陌生人搜索到你的 bot 并白嫖你的 API 额度
"open"（危险！禁止使用！） — 任何人在 Telegram 上搜索到你的机器人都可以直接使用。这意味着全世界任何人都能免费消耗你的 API 费用

推荐设置 session.dmScope: "per-channel-peer"，确保每个 Telegram 用户拥有独立的对话上下文，互不干扰。

Discord 是另一个常用的 OpenClaw 渠道。与 Telegram 不同，Discord 机器人是邀请制的，只有被邀请到服务器的用户才能使用。

访问 discord.com/developers/applications，创建新应用
进入 Bot 页面，点击 Reset Token 获取 Bot Token
在 OAuth2 → URL Generator 中选择 bot 权限
使用生成的邀请链接将 bot 添加到你的 Discord 服务器
将 Token 填入配置文件的 channels.discord.botToken

"channels": { "discord": {

"enabled": true, "botToken": "MTIzNDU2Nzg5...", "dmPolicy": "open", "allowFrom": ["*"]

} }, "plugins": { "entries": {

"discord": { "enabled": true }

} }

Discord 机器人与 Telegram 不同 — Discord bot 必须被邀请到服务器才能被使用，不存在被陌生人搜索到的风险。因此 dmPolicy: "open" 配合 allowFrom: [""] 是安全且推荐的配置。

注意：设置 dmPolicy: "open" 时，必须同时设置 allowFrom: [""]。缺少 allowFrom 会导致配置验证失败。

OpenClaw 也支持飞书（Lark）和钉钉（DingTalk）渠道。由于这两个平台的配置涉及企业应用注册和 Webhook 设置，流程较为复杂。

飞书和钉钉的配置结构与 Telegram/Discord 类似，都在 channels 下添加对应条目，并在 plugins.entries 中启用。具体步骤请参考：

OpenClaw 安装部署教程 — 包含完整的渠道配置指南
微信接入指南 — 微信和国内平台的接入方法

网关（Gateway）是 OpenClaw 的核心入口，负责处理所有外部连接。配置好网关是确保 OpenClaw 正常运行的前提。

gateway.auth 是必填项，用于保护你的 OpenClaw 实例不被未授权访问。最常见的配置错误就是 auth 格式不对。

// 正确格式 — auth 是一个包含 token 的对象 "gateway": { "auth": {

"token": "a1b2c3d4-e5f6-7890-abcd-ef"

} }

// 错误格式 — 以下都会导致启动失败 "gateway": { "auth": "my-token" } // 字符串，错！ "gateway": { "auth": "none" } // 字符串，错！ "gateway": { "auth": { "type": "none" } } // 无效格式，错！

Token 建议使用随机生成的 UUID，可以用 uuidgen 命令或在线 UUID 生成器创建。

OpenClaw 内置了一个 Web 控制台 UI，可以通过浏览器访问网关地址来管理你的AI助手。如果需要从远程浏览器访问（而不只是 localhost），需要设置：

"gateway": { "controlUi": {

"allowInsecureAuth": true

} }

allowInsecureAuth: true 禁用了设备配对验证，允许仅凭 token 即可从任意浏览器访问。在 HTTPS 环境下配合随机 UUID token，这个设置是安全的。

以下是一个完整的 openclaw.json 配置示例，包含了所有常用模块：

{ "models": {

"providers": { "openrouter": { "apiKey": "sk-or-v1-your-openrouter-key" } }

}, "agents": {

"defaults": { "model": { "primary": "openrouter/anthropic/claude-sonnet-4.6" }, "persona": "你是一个友好、专业的AI助手，擅长用中文回答各类问题。", "systemPrompt": "请用简洁、准确的中文回答用户的问题。" }

}, "channels": {

"telegram": { "enabled": true, "botToken": ":ABCdefGHIjklMNOpqrsTUVwxyz", "dmPolicy": "pairing" }, "discord": { "enabled": true, "botToken": "MTIzNDU2Nzg5...", "dmPolicy": "open", "allowFrom": ["*"] }

}, "plugins": {

"entries": { "telegram": { "enabled": true }, "discord": { "enabled": true }, "web-chat": { "enabled": true } }

}, "gateway": {

"auth": { "token": "a1b2c3d4-e5f6-7890-abcd-ef" }, "port": 18789, "controlUi": { "allowInsecureAuth": true }

}, "session": {

"dmScope": "per-channel-peer"

} }

以下是 OpenClaw 配置中最常遇到的错误和解决方法。如果你的 OpenClaw 启动失败或渠道不工作，请逐一对照检查。

问题：多余的逗号、缺少的括号、未闭合的引号等。这是最常见的配置错误。

解决方法：使用在线 JSON 验证工具（如 jsonlint.com）检查语法。注意最后一个元素后面不能有逗号。

// 错误 — 最后一个元素后面有逗号 { "models": { … }, "channels": { … }, ← 这个逗号是多余的 }

// 正确 { "models": { … }, "channels": { … } }

问题：gateway.auth 必须是对象格式 { token: "…" }，不能是字符串。

解决方法：确保 auth 是一个包含 token 字段的对象。

// 错误 — auth 是字符串 "gateway": { "auth": "my-token" }

// 错误 — auth 设置为 none "gateway": { "auth": "none" } "gateway": { "auth": { "type": "none" } }

// 正确 — auth 是对象 "gateway": { "auth": { "token": "my-uuid-token" } }

问题：channels 和 plugins.entries 必须同时启用，渠道才能正常运行。

解决方法：检查对应渠道在 channels 和 plugins.entries 中都已设置 enabled: true。

// 错误 — 只配了 channels，没配 plugins "channels": { "telegram": { "enabled": true, … } } "plugins": { "entries": {} } ← 缺少 telegram 插件

// 正确 — 两处都启用 "channels": { "telegram": { "enabled": true, … } } "plugins": { "entries": { "telegram": { "enabled": true } } }

问题：agents.defaults.model.primary 的值必须以提供商名称开头。

解决方法：格式为：提供商名/模型路径。提供商名必须与 models.providers 中的 key 一致。

// 错误 — 缺少提供商前缀 "primary": "anthropic/claude-sonnet-4.6" // OpenClaw 无法识别该路由到哪个提供商

// 正确 — 使用 openrouter 作为提供商前缀 "primary": "openrouter/anthropic/claude-sonnet-4.6"

// 正确 — 直接使用 anthropic 提供商 "primary": "anthropic/claude-sonnet-4.6" // 但 models.providers 中必须有 anthropic 这个 key

问题：当 Telegram 使用 dmPolicy: "pairing" 时，~/.openclaw/credentials/ 目录必须存在。

解决方法：在挂载的配置目录下手动创建 credentials 文件夹并设置正确权限。

mkdir -p ~/.openclaw/credentials chmod 777 ~/.openclaw/credentials

问题：将 Telegram 的 dmPolicy 设为 "open" 非常危险 — 任何人都可以在 Telegram 上搜索到你的机器人并免费使用。

解决方法：Telegram 必须使用 dmPolicy: "pairing"，确保用户需要通过网关配对才能使用。

// 危险 — 任何人都可以使用你的 bot "telegram": { "dmPolicy": "open", "allowFrom": ["*"] }

// 安全 — 需要通过网关配对 "telegram": { "dmPolicy": "pairing" }

问题：Discord 使用 "pairing" 会导致糟糕的用户体验 — 用户必须先私信 bot 获取代码，再到网关 UI 验证，流程混乱。

解决方法：Discord 应该使用 dmPolicy: "open" 配合 allowFrom: [""]。Discord 机器人本身就是邀请制的，所以 "open" 是安全的。

// Discord 推荐配置 "discord": { "dmPolicy": "open", "allowFrom": [""] }

如果你不想手动编辑 JSON 配置文件，OpenClaw Launch 提供了完整的可视化配置方案：

OpenClaw Launch 的优势：

零 JSON 编辑 — 所有配置通过图形界面完成
内置验证 — 自动检查配置格式，防止语法错误
自动处理网关 — 无需手动配置 HTTPS、认证、端口等
免运维 — 无需自己管理服务器、Docker、SSL证书
一键切换模型 — 在下拉菜单中选择即可，即时生效
$3/月起 — 比自建服务器还便宜，支持支付宝和微信支付

OpenClaw 支持配置热加载（Hot Reload），修改配置后无需重启容器即可生效。但并非所有配置都能热加载：

配置项热加载需要重启 channels. 支持 agents. 支持 models. 支持 plugins. 需要重启 gateway.auth.* 需要重启

这意味着切换模型、修改人设、更改渠道设置等操作都会立即生效。只有新增/删除插件或修改网关认证时才需要重启容器。

修改 agents.defaults.model.primary 的值为新的模型ID即可。例如从 Claude 切换到 GPT：将值从 openrouter/anthropic/claude-sonnet-4.6 改为 openrouter/openai/gpt-5.2。保存后自动生效，无需重启。使用 OpenClaw Launch 则在下拉菜单中直接选择。

在 models.providers 中添加多个提供商的 API Key 即可。每个提供商是一个独立的 key-value 对。当前使用的模型由 agents.defaults.model.primary 决定，切换时只需修改这一个值。

首先检查 JSON 语法是否正确（用 jsonlint.com 验证）。然后检查 OpenClaw 日志看是否有错误信息。如果是 plugins 或 gateway.auth 的修改，需要重启容器才能生效。如果问题持续，尝试完全重启：docker restart openclaw。

删除或重命名当前的 openclaw.json 文件，然后用上面的完整配置示例创建新文件。重启容器后即可使用新配置。使用 OpenClaw Launch 则可以在仪表盘中直接修改任何配置，有误操作也可以重新编辑。

OpenRouter 是一个统一的AI模型网关 — 你用一个 API Key 就能访问所有模型。直接使用提供商（如直接用 OpenAI API Key）则需要为每个提供商分别注册和管理密钥。价格上基本一致，OpenRouter 有少量加价但提供了模型回退和统一计费的便利。新手推荐用 OpenRouter。

国产模型（DeepSeek、Kimi）国内直连，无需代理。海外模型（OpenAI、Claude、Gemini）的 API 需要海外网络环境。使用 OpenClaw Launch 可以完全绕过网络限制 — 平台服务器在海外，所有 API 调用在服务器端完成，你只需通过 Telegram、Discord 或浏览器与AI助手对话。

默认路径是 ~/.openclaw/openclaw.json。使用 Docker 部署时，通过 -v 参数将本地目录挂载到容器的 /home/node/.openclaw。确保目录权限为 777（容器以 node 用户运行，uid 1000）。使用 OpenClaw Launch 则无需关心配置文件位置，平台自动管理。

OpenClaw 配置完整教程

相关推荐