返回
Openclaw-Troubleshooting

02. OpenClaw 配置问题排查完全指南

深入排查 OpenClaw 配置问题，包括配置文件格式、API Key 配置、环境变量冲突、渠道配置错误等。提供配置验证工具和最佳实践。

适用于 OpenClaw v2026.2 | 本文适合遇到配置问题的用户。

TL;DR: 配置文件路径：~/.openclaw/openclaw.json。验证配置：openclaw config validate。API Key 环境变量：ANTHROPIC_API_KEY 或 OPENAI_API_KEY。配置优先级：CLI 参数 > 环境变量 > 配置文件 > 默认值。不要在配置文件中硬编码密钥，使用环境变量或凭据管理。

常见问题速查表

问题 症状 快速解决
配置文件格式错误 JSON parse error 使用 JSON 验证器检查语法
API Key 无效 Invalid API key 检查 Key 格式和环境变量
配置不生效 配置修改后无变化 检查优先级和重启 Gateway
渠道配置错误 Channel not found 验证 Token 和配置格式
环境变量冲突 配置与预期不符 检查环境变量优先级

问题 1：配置文件格式错误

症状

$ openclaw gateway
Error: Failed to parse configuration file
SyntaxError: Unexpected token } in JSON at position 123

原因分析

  1. JSON 语法错误（缺少逗号、括号不匹配等）
  2. 文件编码问题
  3. 包含注释（JSON 标准不支持注释）

解决方案

方案 1：使用 JSON 验证工具

# 使用 jq 验证
cat ~/.openclaw/openclaw.json | jq .

# 使用 Python 验证
python3 -m json.tool ~/.openclaw/openclaw.json

# 使用 Node.js 验证
node -e "console.log(JSON.parse(require('fs').readFileSync('$HOME/.openclaw/openclaw.json', 'utf8')))"

方案 2：重置配置

# 备份错误配置
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.broken

# 使用默认配置
openclaw config reset

# 或重新运行向导
openclaw onboard

方案 3：使用配置验证命令

# 验证配置
openclaw config validate

# 输出示例：
# ✅ JSON syntax valid
# ✅ Required fields present
# ⚠️  Warning: agent.model not set, using default
# ❌ Error: gateway.port must be a number

常见 JSON 错误示例

错误 1：缺少逗号

{
  "agent": {
    "model": "claude-opus-4-6"
    "thinkingLevel": "high"  ❌ 缺少逗号
  }
}

修正：

{
  "agent": {
    "model": "claude-opus-4-6",
    "thinkingLevel": "high"
  }
}

错误 2：多余的逗号

{
  "gateway": {
    "port": 18789,
  },  ❌ 最后一个属性后不应有逗号
}

修正：

{
  "gateway": {
    "port": 18789
  }
}

错误 3：使用了注释

{
  "agent": {
    // 这是注释 ❌ JSON 不支持注释
    "model": "claude-opus-4-6"
  }
}

修正：使用 JSONC（JSON with Comments）或移除注释

预防措施

  • 使用支持 JSON 语法检查的编辑器（VS Code、WebStorm 等）
  • 安装 JSON linter：npm install -g jsonlint
  • 提交前验证：jsonlint ~/.openclaw/openclaw.json

问题 2：API Key 配置问题

症状 1：API Key 未配置

$ openclaw agent --message "你好"
Error: No API key configured for model anthropic/claude-opus-4-6

解决方案

# 方法 1：使用向导配置
openclaw onboard

# 方法 2：设置环境变量
export ANTHROPIC_API_KEY="sk-ant-api03-..."

# 方法 3：写入配置文件
openclaw config set agent.apiKey "sk-ant-api03-..."

# 方法 4：使用凭据管理
openclaw credentials add anthropic --key "sk-ant-api03-..."

症状 2：API Key 格式错误

Error: Invalid API key format

解决方案

检查 Key 格式：

# Anthropic Claude
# 格式：sk-ant-api03-...
export ANTHROPIC_API_KEY="sk-ant-api03-xxxxxxxxxxxxx"

# OpenAI GPT
# 格式：sk-...
export OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxx"

# 验证 Key
openclaw doctor --api-keys

症状 3：API Key 泄露

在日志或配置文件中看到明文 Key。

解决方案

# 1. 撤销旧 Key
# 访问 Anthropic Console 或 OpenAI Platform 撤销泄露的 Key

# 2. 生成新 Key
# 在平台生成新的 API Key

# 3. 使用环境变量而非配置文件
export ANTHROPIC_API_KEY="new-key"

# 4. 从配置文件中移除 Key
openclaw config delete agent.apiKey

# 5. 清理日志
rm ~/.openclaw/logs/*.log

API Key 最佳实践

# ✅ 推荐：使用环境变量
export ANTHROPIC_API_KEY="sk-ant-api03-..."

# ✅ 推荐：使用 .env 文件
cat > ~/.openclaw/.env << EOF
ANTHROPIC_API_KEY=sk-ant-api03-...
OPENAI_API_KEY=sk-...
EOF

# ❌ 不推荐：在配置文件中硬编码
{
  "agent": {
    "apiKey": "sk-ant-api03-..."  # 不安全
  }
}

# ✅ 推荐：使用凭据管理
openclaw credentials add anthropic

预防措施

  • 永远不要在配置文件中硬编码 API Key
  • 不要将 API Key 提交到 Git
  • 定期轮换 API Key
  • 使用 .env 文件并添加到 .gitignore

问题 3：配置不生效

症状

修改配置文件后，行为没有变化。

原因分析

  1. Gateway 未重启
  2. 环境变量覆盖了配置
  3. 配置优先级问题
  4. 修改了错误的配置文件

解决方案

方案 1：重启 Gateway

# 停止当前 Gateway
pkill -f "openclaw gateway"

# 或使用命令
openclaw gateway --stop

# 重新启动
openclaw gateway

# 或使用 daemon 模式
openclaw gateway --daemon --restart

方案 2：检查配置优先级

配置优先级（从高到低）：

1. CLI 参数
2. 环境变量
3. 配置文件
4. 默认值

检查是否有环境变量覆盖：

# 查看所有相关环境变量
env | grep -i openclaw
env | grep -i anthropic
env | grep -i openai

# 检查配置来源
openclaw config get agent.model --verbose

# 输出示例：
# agent.model = claude-opus-4-6
# Source: environment variable ANTHROPIC_MODEL

方案 3：查看实际配置

# 查看所有配置
openclaw config get

# 查看特定配置
openclaw config get agent.model

# 查看配置来源
openclaw config get agent.model --source

# 导出完整配置
openclaw config export > my-config.json

方案 4：检查配置文件路径

# 查看配置文件位置
openclaw config path

# 输出：/home/user/.openclaw/openclaw.json

# 检查是否有多个配置文件
find ~ -name "openclaw.json" 2>/dev/null

# 检查环境变量指定的配置文件
echo $OPENCLAW_CONFIG

预防措施

  • 修改配置后重启 Gateway
  • 使用 openclaw config set 而非手动编辑
  • 定期备份配置文件
  • 使用版本控制管理配置

问题 4：渠道配置错误

症状 1：Telegram Bot 配置失败

$ openclaw channels login telegram
Error: Invalid bot token

解决方案

# 1. 获取正确的 Bot Token
# 与 @BotFather 对话，发送 /newbot 或 /mybots

# 2. 验证 Token 格式
# 格式：123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11

# 3. 测试 Token
curl "https://api.telegram.org/bot<YOUR_TOKEN>/getMe"

# 4. 登录
openclaw channels login telegram
# 输入 Token: 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11

症状 2：WhatsApp 配置失败

Error: WhatsApp authentication failed

解决方案

WhatsApp 配置较复杂，需要：

# 1. 安装 WhatsApp Web 桌面版或使用手机

# 2. 配置方式 1：扫码登录
openclaw channels login whatsapp

# 3. 配置方式 2：使用 WhatsApp Business API
# 需要申请 Business API 账户

# 4. 检查配置
openclaw config get channels.whatsapp

症状 3：Discord Bot 配置失败

Error: Discord token invalid

解决方案

# 1. 创建 Discord Bot
# 访问 https://discord.com/developers/applications

# 2. 获取 Token
# Bot -> Add Bot -> Token -> Copy

# 3. 配置权限
# OAuth2 -> URL Generator -> Bot -> 选择权限

# 4. 邀请 Bot 到服务器
# 使用生成的 URL 邀请

# 5. 配置
openclaw channels login discord

症状 4：渠道未启用

$ openclaw gateway
Warning: No channels configured

解决方案

# 查看已配置的渠道
openclaw channels list

# 启用渠道
openclaw config set channels.telegram.enabled true

# 验证配置
openclaw config get channels

渠道配置清单

每个渠道需要的配置项：

Telegram

{
  "channels": {
    "telegram": {
      "botToken": "123456:ABC-DEF...",
      "enabled": true,
      "dmPolicy": "pairing"
    }
  }
}

Discord

{
  "channels": {
    "discord": {
      "token": "your-bot-token",
      "enabled": true,
      "guilds": {},
      "dmPolicy": "pairing"
    }
  }
}

WhatsApp

{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "dmPolicy": "pairing"
    }
  }
}

问题 5：环境变量冲突

症状

配置与预期不符，使用了错误的值。

原因分析

多个环境变量来源，优先级不明确。

环境变量优先级

1. Shell 环境变量 (export)
2. ~/.bashrc / ~/.zshrc
3. .env 文件
4. systemd 用户服务
5. Docker 环境变量

解决方案

方案 1：检查所有来源

# 检查 Shell 环境变量
env | grep -i openclaw

# 检查 .bashrc
grep -i openclaw ~/.bashrc

# 检查 .env 文件
cat ~/.openclaw/.env

# 检查 systemd 用户服务
systemctl --user show openclaw | grep Environment

方案 2：统一管理环境变量

# 创建统一的 .env 文件
cat > ~/.openclaw/.env << EOF
ANTHROPIC_API_KEY=sk-ant-...
OPENCLAW_PORT=18789
OPENCLAW_BIND=loopback
EOF

# 从 .bashrc 中移除相关配置
# 避免冲突

# 使用 dotenv 加载
openclaw gateway --env-file ~/.openclaw/.env

方案 3：调试环境变量

# 显示配置来源
openclaw config get --verbose

# 输出示例：
# agent.model = claude-opus-4-6
#   Source: environment variable ANTHROPIC_MODEL
#   File: ~/.bashrc:45

预防措施

  • 使用统一的 .env 文件管理环境变量
  • 定期审查 .bashrc 和 .zshrc
  • 使用 openclaw config get --verbose 调试

问题 6：模型配置问题

症状 1：模型不存在

Error: Model 'claude-opus-5' not found

解决方案

# 查看可用模型
openclaw models list

# 输出示例：
# anthropic/claude-opus-4-6
# anthropic/claude-sonnet-4
# anthropic/claude-haiku-3.5
# openai/gpt-4o
# openai/gpt-4-turbo
# openai/gpt-4o-mini

# 设置正确的模型
openclaw config set agent.model anthropic/claude-opus-4-6

症状 2：模型不支持某些功能

Error: Model does not support vision

解决方案

# 检查模型能力
openclaw models show claude-opus-4-6 --capabilities

# 输出示例：
# Model: claude-opus-4-6
# Capabilities:
#   - Text generation ✅
#   - Vision ✅
#   - Tool use ✅
#   - Code execution ❌

# 选择支持所需功能的模型
openclaw config set agent.model anthropic/claude-sonnet-4

症状 3：Fallback 模型配置错误

Error: Invalid fallback configuration

解决方案

{
  "models": {
    "fallback": [
      {
        "model": "anthropic/claude-sonnet-4",
        "condition": "rate_limit"
      },
      {
        "model": "openai/gpt-4o-mini",
        "condition": "error"
      }
    ]
  }
}

验证配置：

# 验证 fallback 配置
openclaw config validate --fallback

# 测试 fallback
openclaw agent --message "test" --simulate-rate-limit

问题 7：沙箱配置问题

症状

Error: Sandbox mode 'invalid' is not supported

解决方案

# 查看支持的沙箱模式
openclaw config get agents.defaults.sandbox.mode --help

# 可选值：off, non-main, always

# 设置沙箱模式
openclaw config set agents.defaults.sandbox.mode non-main

沙箱配置示例

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main",
        "allowlist": ["read", "write", "bash"],
        "denylist": ["browser", "canvas"],
        "container": {
          "image": "openclaw/sandbox:latest",
          "timeout": 30000
        }
      }
    }
  }
}

配置管理最佳实践

1. 使用版本控制

# 初始化 Git 仓库
cd ~/.openclaw
git init
git add openclaw.json
git commit -m "Initial configuration"

# 修改配置后提交
git diff openclaw.json
git commit -am "Update model configuration"

2. 多环境配置

# 创建多个配置文件
~/.openclaw/
├── openclaw.json          # 默认配置
├── openclaw.dev.json      # 开发环境
├── openclaw.prod.json     # 生产环境
└── openclaw.test.json     # 测试环境

# 使用特定配置
openclaw gateway --config ~/.openclaw/openclaw.prod.json

3. 配置备份

# 定期备份
tar -czvf openclaw-config-$(date +%Y%m%d).tar.gz ~/.openclaw/openclaw.json

# 或使用云存储同步
# rsync -av ~/.openclaw/ user@backup-server:~/openclaw-backup/

4. 配置验证脚本

创建 validate-config.sh：

#!/bin/bash

echo "验证 OpenClaw 配置..."

# 1. JSON 语法检查
if ! jq empty ~/.openclaw/openclaw.json 2>/dev/null; then
    echo "❌ JSON 语法错误"
    exit 1
fi
echo "✅ JSON 语法正确"

# 2. 必需字段检查
required_fields=(
    "agent.model"
    "gateway.port"
)

for field in "${required_fields[@]}"; do
    if ! openclaw config get "$field" &>/dev/null; then
        echo "❌ 缺少必需字段: $field"
        exit 1
    fi
done
echo "✅ 必需字段存在"

# 3. API Key 检查
if [ -z "$ANTHROPIC_API_KEY" ] && [ -z "$OPENAI_API_KEY" ]; then
    echo "⚠️  未配置 API Key"
fi
echo "✅ API Key 已配置"

# 4. 端口检查
port=$(openclaw config get gateway.port)
if lsof -i :$port &>/dev/null; then
    echo "⚠️  端口 $port 已被占用"
else
    echo "✅ 端口 $port 可用"
fi

echo "配置验证完成"

小结

配置问题是 OpenClaw 使用中最常见的问题类型：

  1. JSON 格式：使用验证工具，避免语法错误
  2. API Key：使用环境变量，不要硬编码
  3. 配置优先级：理解 CLI > 环境变量 > 文件 > 默认
  4. 渠道配置：按步骤获取 Token 并配置
  5. 环境变量冲突：统一管理，避免多处配置
  6. 模型配置：选择正确的模型名称和能力

配置管理的核心原则：

  • 安全：不泄露敏感信息
  • 清晰：配置来源明确
  • 可维护：使用版本控制
  • 可验证：配置验证工具

下一篇预告：03. 连接问题排查 — 解决渠道连接、网络超时、WebSocket 错误等连接问题。

更新记录：

  • 2026-03-06：初版发布，涵盖 7 大类配置问题

系列导航：