背景

我是小白，还好现在有ai这个耐心的辅导员，可以帮我推平前面的坑！

最近在部署和配置 OpenClaw 时，遇到了两个棘手的问题。经过一番排查，发现都是配置文件和环境变量设置不当引起的。特此记录，希望能帮助遇到类似问题的朋友。

问题一：HTTP 500 Illegal group reference 错误

现象

通过 TUI 或 Web 界面与 OpenClaw 对话时， consistently 收到以下错误：

HTTP 500: java.lang.IllegalArgumentException: Illegal group reference

原因分析

在 openclaw.json 配置文件中，API Key 的引用方式不正确：

"apiKey": "$My_API_Key"  // ❌ 错误写法

这种写法导致 OpenClaw 在解析环境变量时，将 $My_API_Key 视为正则表达式引用，而不是完整的环境变量名。

解决方案

修改配置文件，使用 ${} 完整包裹环境变量名：

"apiKey": "${My_API_Key}"  // ✅ 正确写法

当然最稳妥的最佳方案是直接用聊天让 龙虾自己解决，让他不要用明文改用环境变量，它就会将变量写入 ~/.openclaw/.env
DASHSCOPE_API_KEY=xxxxxx

问题二：gateway restart timeout 错误

现象

执行 openclaw gateway restart 命令时，出现超时错误：

Gateway restart timed out after 60s waiting for health checks.```

通过后台报错 可以定位
journalctl --user -u openclaw-gateway.service -n 200 --no-pager

![在这里插入图片描述](https://i-blog.csdnimg.cn/direct/8e3e2c4a3d774c0ca1bf79ca83cf4305.png#pic_center)


### 原因分析
检查 `.bashrc` 或 `.bash_profile` 中的环境变量设置，发现问题：
```bash
export ALI_API_KEY=sk-sp-xxxxxxxx  // ❌ 错误写法

当 API Key 包含特殊字符（如连字符、斜杠等）时，不加引号会导致 shell 解释错误。

解决方案

在 .bashrc 中使用单引号包裹 API Key：

export ALI_API_KEY='sk-sp-xxxxxxxx'  // ✅ 正确写法

修改后执行：

source ~/.bashrc  # 重新加载配置

【小白科普】Shell 中的变量引用符号详解

对于刚接触 Linux 的朋友来说，$、${}、''、"" 这些符号确实容易混淆。下面我用最通俗的方式解释一下：

1. $变量名 vs ${变量名}

$变量名：最简单的变量引用方式

name="张三"
echo $name  # 输出：张三

${变量名}：更严谨的变量引用方式

name="张三"
echo ${name}  # 输出：张三

# ${} 的优势：明确变量的边界
echo $name哥    # 错误！Shell 会去找 "name哥" 这个变量
echo ${name}哥  # 正确！输出：张三哥

为什么 OpenClaw 要用 ${}？
因为 OpenClaw 在解析配置文件时，需要明确知道变量名的结束位置。$My_API_Key 这种写法有歧义，而 ${My_API_Key} 则清晰明了。

2. 单引号 '' vs 双引号 ""

这是一个非常重要的区别：

单引号 ''：所见即所得，里面的内容原样输出

name="张三"
echo '我的名字是 $name'  # 输出：我的名字是 $name（变量未被解析）
echo 'sk-sp-123'         # 输出：sk-sp-123（原样输出）

双引号 ""：会解析里面的变量和特殊符号

name="张三"
echo "我的名字是 $name"  # 输出：我的名字是张三（变量被解析）
echo "sk-sp-123"         # 输出：sk-sp-123（双引号也可以）

为什么 API Key 要用单引号？

# 假设 API Key 是：sk-sp-123
export KEY=sk-sp-123     # 有问题！连字符会被特殊处理
export KEY='sk-sp-123'   # 正确！原样赋值

# 更极端的例子
export KEY=a&b           # 错误！& 会被解释为后台运行命令
export KEY='a&b'         # 正确！作为普通字符串

3. 实际场景演示

# 场景1：API Key 包含特殊字符
export API_KEY='sk-abc-123$%^'  # 单引号保护所有特殊字符

# 场景2：需要引用其他变量
export BASE_URL="https://${API_KEY}@api.example.com"  # 双引号解析变量

# 场景3：混合使用
echo '直接输出 $API_KEY 的值是' "$API_KEY"  # 输出：直接输出 $API_KEY 的值是 sk-abc-123$%^

4. 快速记忆口诀

• $var：简单引用变量
• ${var}：明确变量边界（推荐在配置文件中使用）
• '内容'：内容原样输出，适合 API Key、密码等（安全）
• "内容"：内容会解析变量，适合需要变量替换的场景

经验总结

1. 环境变量引用格式：在 JSON 配置文件中引用环境变量，务必使用 ${VAR_NAME} 格式
2. 特殊字符处理：在 .bashrc 中设置包含特殊字符的环境变量时，一定要用引号包裹
3. 配置验证：修改配置后，建议先测试再部署到生产环境
4. 安全提示：API Key 等敏感信息，推荐使用单引号避免意外解析

这两个问题看似简单，但错误信息并不直观，容易让人走弯路。希望这篇记录能帮您节省排查时间。

---

相关标签：OpenClaw, 环境变量, Shell编程, Java异常, 配置错误, 运维经验