OpenClaw 配置完整教程

什么是 OpenClaw 配置文件？

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": { ... }      // 网关认证和端口设置
}

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

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

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

"channels": {
  "telegram": {
    "enabled": true,
    "botToken": "123456:ABC-DEF...",
    "dmPolicy": "pairing"
  },
  "discord": {
    "enabled": true,
    "botToken": "MTIz...",
    "dmPolicy": "open",
    "allowFrom": ["*"]
  }
}

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

"gateway": {
  "auth": {
    "token": "你的随机UUID令牌"
  },
  "port": 18789,
  "controlUi": {
    "allowInsecureAuth": true
  }
}

模型配置详解（最重要！）

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

模型ID格式说明

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

关键规则：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 V4 Flash
"agents": {
  "defaults": {
    "model": { "primary": "openrouter/deepseek/deepseek-v4-flash" }
  }
}

// 切换到 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 就能在它们之间切换，不需要改动其他任何配置。

各提供商 API Key 获取步骤

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

API 配置与密钥管理

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

API Key 安全最佳实践

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

OpenRouter 作为统一网关

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

OpenRouter 的优势：

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

BYOK（Bring Your Own Key）自带密钥

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

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

Telegram 渠道配置详解

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

获取 Telegram Bot Token

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

Telegram 配置示例

"channels": {
  "telegram": {
    "enabled": true,
    "botToken": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",
    "dmPolicy": "pairing"
  }
},
"plugins": {
  "entries": {
    "telegram": { "enabled": true }
  }
}

dmPolicy 设置（重要！）

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

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

会话隔离

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

Discord 渠道配置详解

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

获取 Discord Bot Token

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

Discord 配置示例

"channels": {
  "discord": {
    "enabled": true,
    "botToken": "MTIzNDU2Nzg5...",
    "dmPolicy": "open",
    "allowFrom": ["*"]
  }
},
"plugins": {
  "entries": {
    "discord": { "enabled": true }
  }
}

Discord 为什么用 "open"？

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-ef1234567890"
  }
}

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

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

控制台 UI 设置

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": "123456789: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-ef1234567890"
    },
    "port": 18789,
    "controlUi": {
      "allowInsecureAuth": true
    }
  },
  "session": {
    "dmScope": "per-channel-peer"
  }
}

常见配置错误及排查

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

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

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

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

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

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

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

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

// 错误 — 缺少提供商前缀
"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

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

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

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

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

OpenClaw Launch 可视化配置（推荐）

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

1. 注册登录 — 使用 Google、GitHub 或邮箱注册 OpenClaw Launch 账号
2. 选择模型 — 在可视化界面中从下拉菜单选择AI模型，无需记忆模型ID格式
3. 配置渠道 — 粘贴 Telegram Bot Token 或 Discord Bot Token，平台自动处理 dmPolicy、plugins 等配置
4. 设置人设 — 在文本框中输入AI助手的人设和系统提示词
5. 一键部署 — 点击「部署」按钮，10秒内你的AI助手上线运行
6. 随时修改 — 在仪表盘中随时修改模型、渠道、人设等任何配置，保存即时生效

OpenClaw Launch 的优势：

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

配置热加载说明

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

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

常见问题

如何切换AI模型？

修改 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 和直接使用提供商 API 有什么区别？

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 则无需关心配置文件位置，平台自动管理。