OpenClaw 配置教程

OpenClaw（原 Clawdbot/Moltbot）是一个开源的个人 AI 助手系统，支持多种消息渠道（WhatsApp、Telegram、Discord 等）和多个 AI 模型提供商。通过配置自定义 provider 可以连接中转服务。

系统要求

Node.js >= 22，支持 Windows / macOS / Linux

安装 OpenClaw

bash

# 全局安装
npm install -g openclaw@latest
# 镜像加速安装
npm install -g openclaw@latest --registry=https://registry.npmmirror.com
# 验证安装
openclaw --version

运行初始化向导

bash

openclaw onboard --install-daemon

向导选项说明：

选项	推荐值
Security 安全确认	Yes
Onboarding mode	Manual (手动配置)
What do you want to set up?	Local gateway (this machine)
Model/auth provider	Skip for now 或 Back
Gateway port	18789 (默认)
Gateway bind	LAN (0.0.0.0)
Gateway auth	Token
Tailscale exposure	Off (除非需要远程访问)
Configure chat channels now?	No (先跳过)
Set GOOGLE_PLACES_API_KEY?	No
Configure skills now?	No 或 Skip for now

向导完成后会自动安装 Gateway 后台服务。如果提示 "Model check: No auth configured"，这是正常的，后面会手动配置中转服务。

配置文件位置

系统	路径
macOS / Linux	`~/.openclaw/openclaw.json`
Windows	`C:\Users\用户名\.openclaw\openclaw.json`

打开配置文件：

macOS / LinuxWindows PowerShell

bash

nano ~/.openclaw/openclaw.json
# 或使用 VS Code
code ~/.openclaw/openclaw.json

powershell

notepad $env:USERPROFILE\.openclaw\openclaw.json
# 或使用 VS Code
code $env:USERPROFILE\.openclaw\openclaw.json

完整配置示例

Claude 分组Codex 分组

json

{
  "agents": {
    "defaults": {
      "workspace": "~/clawd",
      "model": {
        "primary": "nexus/claude-opus-4-6"
      },
      "compaction": {
        "mode": "safeguard"
      },
      "maxConcurrent": 4,
      "subagents": {
        "maxConcurrent": 8
      }
    }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "nexus": {
        "baseUrl": "https://api.flymux.com",
        "apiKey": "sk-你的API密钥",
        "api": "anthropic-messages",
        "models": [
          {
            "id": "claude-sonnet-4-6",
            "name": "Claude Sonnet 4.5",
            "contextWindow": 180000,
            "maxTokens": 8192
          },
          {
            "id": "claude-opus-4-5-20251101",
            "name": "Claude Opus 4.5",
            "contextWindow": 180000,
            "maxTokens": 8192
          },
          {
            "id": "claude-opus-4-6",
            "name": "Claude Opus 4.6",
            "contextWindow": 180000,
            "maxTokens": 8192
          }
        ]
      }
    }
  },
  "messages": {
    "ackReactionScope": "group-mentions"
  },
  "commands": {
    "native": "auto",
    "nativeSkills": "auto"
  },
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "lan",
    "controlUi": {
      "dangerouslyAllowHostHeaderOriginFallback": true
    },
    "auth": {
      "mode": "token",
      "token": "undefined"
    },
    "tailscale": {
      "mode": "off",
      "resetOnExit": false
    }
  },
  "skills": {
    "install": {
      "nodeManager": "npm"
    }
  }
}

json

{
  "agents": {
    "defaults": {
      "workspace": "~/clawd",
      "model": {
        "primary": "nexus_codex/gpt-5.4"
      },
      "compaction": {
        "mode": "safeguard",
        "reserveTokensFloor": 40000
      },
      "thinkingDefault": "high",
      "timeoutSeconds": 900,
      "maxConcurrent": 4,
      "subagents": {
        "maxConcurrent": 8
      }
    }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "nexus_codex": {
        "baseUrl": "https://api.flymux.com/v1",
        "apiKey": "sk-你的API密钥",
        "api": "openai-responses",
        "models": [
          {
            "id": "gpt-5.3",
            "name": "GPT 5.3",
            "contextWindow": 400000,
            "maxTokens": 128000,
            "reasoning": true,
            "input": ["text", "image"],
            "cost": { "input": 1.75, "output": 14, "cacheRead": 0.175, "cacheWrite": 0 }
          },
          {
            "id": "gpt-5.4",
            "name": "GPT 5.4",
            "contextWindow": 272000,
            "maxTokens": 128000,
            "reasoning": true,
            "input": ["text", "image"],
            "cost": { "input": 2.5, "output": 15, "cacheRead": 0.25, "cacheWrite": 0 }
          },
          {
            "id": "gpt-5.4-pro",
            "name": "GPT 5.4 Pro",
            "contextWindow": 272000,
            "maxTokens": 128000,
            "reasoning": true,
            "input": ["text", "image"],
            "cost": { "input": 20, "output": 120, "cacheRead": 2, "cacheWrite": 0 }
          }
        ]
      },
      "nexus_codex_1m": {
        "baseUrl": "https://api.flymux.com/v1",
        "apiKey": "sk-你的API密钥",
        "api": "openai-responses",
        "models": [
          {
            "id": "gpt-5.4",
            "name": "GPT 5.4 (1M)",
            "contextWindow": 1050000,
            "maxTokens": 128000,
            "reasoning": true,
            "input": ["text", "image"],
            "cost": { "input": 2.5, "output": 15, "cacheRead": 0.25, "cacheWrite": 0 }
          }
        ]
      }
    }
  },
  "messages": {
    "ackReactionScope": "group-mentions"
  },
  "commands": {
    "native": "auto",
    "nativeSkills": "auto"
  },
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "lan",
    "controlUi": {
      "dangerouslyAllowHostHeaderOriginFallback": true
    },
    "auth": {
      "mode": "token",
      "token": "undefined"
    },
    "tailscale": {
      "mode": "off",
      "resetOnExit": false
    }
  },
  "skills": {
    "install": {
      "nodeManager": "npm"
    }
  }
}

WARNING

将 sk-你的API密钥 替换为你在控制台创建的实际密钥。

验证配置

bash

# 检查配置问题
openclaw doctor
# 查看已配置的模型
openclaw models list

如果 models list 显示你配置的模型且 Auth 为 yes，说明配置成功。

启动使用

bash

# 启动 Gateway 服务（后台运行）
openclaw gateway install
openclaw gateway start
# 或前台运行（可以看到日志，调试用）
openclaw gateway --verbose
# 启动 TUI 交互界面
openclaw tui
# 命令行对话
openclaw agent --agent main --message "Hello"

常用命令

命令	说明
`openclaw gateway`	前台启动 Gateway 服务
`openclaw gateway --verbose`	前台启动并显示详细日志
`openclaw gateway install`	安装 Gateway 后台服务
`openclaw gateway start`	启动后台服务
`openclaw gateway stop`	停止后台服务
`openclaw tui`	启动 TUI 交互界面
`openclaw models list`	查看已配置的模型
`openclaw doctor`	检查配置问题
`openclaw doctor --fix`	自动修复配置问题
`openclaw plugins enable telegram`	启用 Telegram 插件

配置 Telegram

OpenClaw 需要配置一个对话界面来使用，以下以 Telegram 为例：

1. 获取 Telegram Bot Token

在 Telegram 中搜索 @BotFather
发送 /newbot
按提示设置 bot 名称
获得 Bot Token（格式：123456789:ABCdefGHIjklMNOpqrsTUVwxyz）

2. 启用 Telegram 插件

bash

openclaw plugins enable telegram

3. 配置 Bot Token

bash

openclaw config set channels.telegram.botToken "YOUR_BOT_TOKEN"

4. 启动 Gateway

bash

openclaw gateway
# 如果报错，先停止再启动
openclaw gateway stop
openclaw gateway

5. 配对验证

在 Telegram 中找到你的 bot，发送任意消息
Bot 会返回一个验证码
在终端执行：

bash

openclaw pairing approve telegram YOUR_CODE

完成配对后即可在 Telegram 中与 AI 对话。

常见配置问题

baseUrl 格式错误（最常见）

Claude 分组使用 https://api.flymux.com，Codex 分组使用 https://api.flymux.com/v1，末尾不要加斜杠：

正确："baseUrl": "https://api.flymux.com" 或 "baseUrl": "https://api.flymux.com/v1"
错误："baseUrl": "https://api.flymux.com/" (末尾多了斜杠)
错误："baseUrl": "https://api.flymux.com/api" (路径错误)

gateway.mode 未设置

必须设置 gateway.mode，否则会报错 "Gateway start blocked"

模型格式错误

正确："primary": "nexus/claude-opus-4-6"
错误："primary": "claude-opus-4-6"

故障排查

bash

# 检查配置问题
openclaw doctor
# 自动修复
openclaw doctor --fix
# 查看模型状态
openclaw models status
# 查看日志
openclaw logs --follow

错误信息	解决方案
No API key found	检查 apiKey 配置是否正确
Gateway start blocked	添加 `"mode": "local"` 到 gateway 配置
Connection refused	检查 baseUrl 和网络连接
401 Unauthorized	检查 apiKey 是否正确
404 Not Found	检查 baseUrl 路径是否正确