OpenClaw 配置指南

个人 AI 助手，支持终端 TUI、Web Dashboard 和多种聊天平台

📋 简介

OpenClaw 是一款运行在你自己设备上的个人 AI 助手，支持终端 TUI 交互、Web Dashboard 管理，以及通过 WhatsApp、Telegram、Slack、Discord、微信等多种聊天平台进行远程对话。

官方网站：https://openclaw.ai | 官方文档：https://docs.openclaw.ai

⚠️ 适用环境

此教程适合 Linux 云服务器、macOS 和 Windows（通过 WSL2） 系统用户。需要 Node.js 22.16+ 或 24（推荐）。

🚨 遇到 403/400 错误或提示 "client 不支持"？

使用 TokenSwitch 渠道时，必须在供应商配置中添加 headers 字段，否则请求可能返回 403、400 错误或提示类似 client not supported（客户端不支持）的报错：

json

"headers": {
  "User-Agent": "claude-cli/2.0.76 (external, cli)",
  "Authorization": "Bearer sk-xxxx"
}

Authorization 的值必须与 apiKey 一致，格式为 Bearer sk-你的密钥
User-Agent 必须保持示例中的格式，不可省略或随意修改
Claude 和 Codex 的 User-Agent 不同，请参考下方完整配置
修改后执行 openclaw gateway restart 重启网关生效

详见下方完整配置实例。

资源	地址
OpenClaw 官网	https://openclaw.ai
官方文档	https://docs.openclaw.ai
GitHub	https://github.com/openclaw/openclaw
Discord	https://discord.gg/clawd

功能特点

终端 TUI：命令行交互界面，适合 SSH 环境
Web Dashboard：浏览器可视化管理面板
多平台聊天：支持 WhatsApp、Telegram、Slack、Discord、微信、QQ 等 20+ 平台
多模型支持：Claude、GPT 等多种模型
Gateway 网关：内置网关服务，支持反向代理
Skill 扩展：可通过 Dashboard 安装扩展技能
Canvas：实时可控的 Canvas 渲染

安装与初始化

第一步：运行安装脚本

登录服务器 SSH 或在 macOS 终端中运行以下命令：

bash

curl -fsSL https://openclaw.ai/install.sh | bash

耐心等待安装流程结束。

第二步：初始化配置（推荐使用 onboard）

推荐使用 openclaw onboard 进行引导式初始化，它会逐步引导你完成 Gateway、工作区、频道和技能的配置：

bash

openclaw onboard

也可以使用 openclaw init 进行快速初始化：

bash

openclaw init

安装过程中会依次出现以下选项，按照说明操作：

步骤	选择	说明
启动方式	QuickStart	快速开始模式
供应商设置	Skip for now	先跳过，后续手动编辑配置文件
适配器选择	anthropic	选择 Anthropic 适配器
模型选择	opus-4.5	或选择你需要的模型
社交适配器	按需选择	如 Telegram（可选）
Skill 安装	跳过	后续可通过 Dashboard 安装
Hook 选择	全选	使用空格键全选后回车确认
打开方式	跳过	先跳过
Shell 补全	yes	安装命令行自动补全

渠道与模型配置

第一步：编辑配置文件

打开 OpenClaw 的配置文件进行编辑：

bash

vim ~/.openclaw/openclaw.json

参照下方完整配置实例填入你的供应商和模型信息。

第二步：填入 API Key

在 models.providers 中配置供应商信息，将 apiKey 和 headers.Authorization 替换为你在 TokenSwitch 控制台创建的 API Key。

第三步：重启网关

bash

openclaw gateway restart

第四步：验证配置

运行以下命令进入 TUI 界面测试模型是否正常：

bash

openclaw tui

测试成功后输入 /quit 退出 TUI。

完整配置实例

以下是一份接入 TokenSwitch 渠道的 openclaw.json 完整配置参考（路径：~/.openclaw/openclaw.json）：

💡 说明

配置中的 sk-xxxx 和 xxxxx 为占位符，请替换为你自己的 API Key 和 Bot Token。

json

{
  "messages": {
    "ackReactionScope": "group-mentions"
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "tokenswitch-claude/claude-opus-4-5-20251101"
      },
      "maxConcurrent": 4,
      "subagents": {
        "maxConcurrent": 8
      },
      "compaction": {
        "mode": "safeguard"
      },
      "workspace": "/root/.openclaw/workspace"
    }
  },
  "models": {
    "providers": {
      "tokenswitch-claude": {
        "baseUrl": "https://tokenswitch.cc/v1",
        "apiKey": "sk-xxxx",
        "api": "openai-completions",
        "headers": {
          "User-Agent": "claude-cli/2.0.76 (external, cli)",
          "Authorization": "Bearer sk-xxxx"
        },
        "models": [
          {
            "id": "claude-opus-4-5-20251101",
            "name": "claude-opus-4-5-20251101",
            "contextWindow": 200000,
            "maxTokens": 32000,
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            }
          }
        ]
      },
      "tokenswitch-codex": {
        "baseUrl": "https://tokenswitch.cc/v1",
        "apiKey": "sk-xxxx",
        "api": "openai-responses",
        "headers": {
          "User-Agent": "codex_cli_rs/0.77.0 (Windows 10.0.26100; x86_64) WindowsTerminal",
          "Authorization": "Bearer sk-xxxx"
        },
        "models": [
          {
            "id": "gpt-5.4",
            "name": "gpt-5.4",
            "contextWindow": 200000,
            "maxTokens": 32000,
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            }
          }
        ]
      }
    }
  },
  "gateway": {
    "mode": "local",
    "auth": {
      "mode": "token",
      "token": "xxxxx"
    },
    "port": 18789,
    "bind": "loopback",
    "tailscale": {
      "mode": "off",
      "resetOnExit": false
    }
  },
  "auth": {
    "profiles": {}
  },
  "plugins": {
    "entries": {
      "telegram": {
        "enabled": true
      }
    }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "xxxxx"
    }
  },
  "logging": {
    "level": "trace",
    "consoleLevel": "debug",
    "consoleStyle": "pretty"
  },
  "commands": {
    "restart": true
  },
  "skills": {
    "install": {
      "nodeManager": "npm"
    }
  }
}

关键字段说明

字段	说明
`agents.defaults.model.primary`	默认使用的模型，格式为 `供应商名/模型ID`
`agents.defaults.maxConcurrent`	主代理最大并发数
`agents.defaults.subagents.maxConcurrent`	子代理最大并发数
`agents.defaults.compaction.mode`	上下文压缩模式，`safeguard` 为安全模式
`agents.defaults.workspace`	工作区目录路径，按你的系统修改
`models.providers`	模型供应商配置，可配置多个供应商
`models.providers.*.baseUrl`	API 基础地址，统一为 `https://tokenswitch.cc/v1`
`models.providers.*.apiKey`	对应分组的 API Key
`models.providers.*.api`	接口协议：Claude 用 `openai-completions`，Codex 建议用 `openai-responses`
`models.providers.*.headers`	请求头，需包含 `User-Agent` 和 `Authorization`
`gateway.port`	网关监听端口，默认 `18789`
`gateway.bind`	绑定模式，`loopback` 仅本机访问
`channels.telegram.botToken`	Telegram Bot Token，通过 @BotFather 获取
`logging.level`	日志级别，排查问题时可设为 `trace`

⚠️ 注意事项

Headers 中的 Authorization 必须与 apiKey 保持一致，格式为 Bearer sk-xxxx
Claude 和 Codex 的 User-Agent 不同：Claude 使用 claude-cli/... 格式，Codex 使用 codex_cli_rs/... 格式
Codex 建议使用 openai-responses 模式
workspace 路径：Windows 用户使用 \\ 双反斜杠，Linux/macOS 用户使用 / 正斜杠（如 /root/.openclaw/workspace）
cost 全部设为 0：通过 TokenSwitch 中转使用时无需在本地计费

浏览器访问 Dashboard

获取 Dashboard URL

在控制台运行命令获取 Dashboard URL，在浏览器中访问即可进入管理面板。

⚠️ 服务器用户注意

如果你在远程服务器运行 OpenClaw，需要：

1. 配置反向代理

使用 Nginx 或其他反向代理工具反代 OpenClaw 服务，并设置 SSL 证书。

2. 修改配置文件

编辑 ~/.openclaw/openclaw.json，在 gateway 字段下添加：

json

"controlUi": {
  "allowInsecureAuth": true
}

3. 重启网关

bash

openclaw gateway restart

访问带有 Token 的 Dashboard URL 即可进入后台界面。

配置 Telegram Bot（可选）

OpenClaw 支持 WhatsApp、Telegram、Slack、Discord、微信、QQ 等 20+ 聊天平台。以下以 Telegram 为例：

在 Telegram 中通过 @BotFather 创建 Bot，获取 Bot Token
在 openclaw.json 的 channels.telegram.botToken 中填入 Token
重启网关：openclaw gateway restart
在 Telegram 中与 Bot 对话，获取 Pairing Code
在控制台运行授权命令：

bash

openclaw pairing approve telegram 你的Pairing_Code

配对成功后，即可通过 Telegram Bot 与 OpenClaw 进行远程对话。

常见问题

安装脚本执行失败？

确认网络连接正常，能访问 openclaw.ai
确认系统已安装 curl 和 bash
如果在国内服务器，可能需要配置代理

遇到 403/400 错误或提示 "client 不支持"？

如果请求返回 403、400 错误或提示类似 client not supported（客户端不支持），说明缺少正确的请求头。必须在供应商配置中添加 headers 字段：

json

"headers": {
  "User-Agent": "claude-cli/2.0.76 (external, cli)",
  "Authorization": "Bearer sk-xxxx"
}

🚨 重要

headers 中的 Authorization 值必须与 apiKey 一致，格式为 Bearer sk-你的密钥
User-Agent 必须保持示例格式，否则请求会被拦截
Claude 和 Codex 使用不同的 User-Agent，请参考完整配置实例
配置完成后执行 openclaw gateway restart 重启网关

Gateway 重启后模型仍不可用？

检查 API Key 是否正确填入
确认 Key 对应的分组支持你选择的模型
查看 OpenClaw 日志排查具体错误：openclaw gateway logs

OpenClaw 配置指南

相关链接

功能特点

安装与初始化

第一步：运行安装脚本

第二步：初始化配置（推荐使用 onboard）

渠道与模型配置

第一步：编辑配置文件

第二步：填入 API Key

第三步：重启网关

第四步：验证配置

完整配置实例

关键字段说明

浏览器访问 Dashboard

获取 Dashboard URL

配置 Telegram Bot（可选）

常见问题

安装脚本执行失败？

遇到 403/400 错误或提示 "client 不支持"？

Gateway 重启后模型仍不可用？

更多问题

OpenClaw 配置指南 ​

相关链接 ​

功能特点 ​

安装与初始化 ​

第一步：运行安装脚本 ​

第二步：初始化配置（推荐使用 onboard） ​

渠道与模型配置 ​

第一步：编辑配置文件 ​

第二步：填入 API Key ​

第三步：重启网关 ​

第四步：验证配置 ​

完整配置实例 ​

关键字段说明 ​

浏览器访问 Dashboard ​

获取 Dashboard URL ​

配置 Telegram Bot（可选） ​

常见问题 ​

安装脚本执行失败？ ​

遇到 403/400 错误或提示 "client 不支持"？ ​

Gateway 重启后模型仍不可用？ ​

更多问题 ​

OpenClaw 配置指南

相关链接

功能特点

安装与初始化

第一步：运行安装脚本

第二步：初始化配置（推荐使用 onboard）

渠道与模型配置

第一步：编辑配置文件

第二步：填入 API Key

第三步：重启网关

第四步：验证配置

完整配置实例

关键字段说明

浏览器访问 Dashboard

获取 Dashboard URL

配置 Telegram Bot（可选）

常见问题

安装脚本执行失败？

遇到 403/400 错误或提示 "client 不支持"？

Gateway 重启后模型仍不可用？

更多问题