OpenClaw 配置详解：openclaw.json 完全指南

本教程将带你全面掌握 openclaw.json 配置文件的所有核心设置，让你从零开始定制自己的 OpenClaw 助手。

# Linux/macOS
~/.openclaw/openclaw.json

# Windows
C:\Users\\.openclaw\openclaw.json

首次运行时，OpenClaw 会自动生成基础配置。编辑此文件即可启动你的定制之旅。

1. 基础设置（gateway 区块）

{
  "gateway": {
    "bind": "0.0.0.0:18789",      # 监听地址：绑定所有网卡，端口自定义
    "cors": true,                 # 启用跨域（Web 前端调用需要）
    "logLevel": "info"            # 日志级别：debug|info|warn|error
  }

• bind：127.0.0.1:18789 仅本机访问，0.0.0.0:18789 允许局域网连接
• cors：设为 true 才允许浏览器跨域请求
• logLevel：debug 适合排查问题，生产环境推荐 info

2. 模型配置（models 区块）

"models": {
  "default": "ollama/qwen3.5:9b",           
  "fallback": "zai/glm-5"                   
}

说明：

• default：默认模型，本地优先（Ollama）
• fallback：当本地模型不可用时自动切换到云端备用模型

切换模型供应商示例：

# 全云端配置（无本地模型时）
"models": {
  "default": "zai/glm-5",
  "fallback": "moonshot/kimi-k2.5"
}

# 混合模式：Qwen + Kimi 交替使用
"models": {
  "default": "ollama/qwen3.5:9b",
  "fallback": "moonshot/kimi-k2.5"
}

3. 网络代理设置（proxy 区块）

"proxy": {
  "http": "http://127.0.0.1:7897",         
  "https": "http://127.0.0.1:7897"         
}

⚠️ 重要：如果使用代理上网，必须在服务文件中设置环境变量：
Environment="HTTP_PROXY=http://127.0.0.1:7897"

# systemd 服务文件示例
[Service]
Environment="HTTP_PROXY=http://127.0.0.1:7897"
Environment="HTTPS_PROXY=http://127.0.0.1:7897"
Restart=always

4. 通信渠道配置（channels 区块）

"channels": {
  "telegram": {
    "enabled": true,
    "botToken": "xxxxx:yyyyy",          # Telegram Bot Token
    "allowFrom": [6327632490]           # 白名单用户 ID
  },
  "feishu": {
    "enabled": true,
    "appId": "cli_your_app_id"          # 飞书 App ID
  }
}

渠道说明：

• Telegram：通过 BotFather 创建 bot，获取 token
  allowFrom限制只允许特定用户交互（安全）
• 飞书：需先配置 Feishu App，获得 appId
• 禁用所有渠道（调试用）：

# 临时关闭所有通信渠道
"channels": {
  "telegram": {"enabled": false},
  "feishu": {"enabled": false}
}

5. TTS/STT 配置（voice 区块）

"voice": {
  "tts": "edge-tts",                     
  "stt": "faster-whisper"                
}

工具选项：

• TTS（文本转语音）：edge-tts（免费）或 openai-whisper-api
• STT（语音转文本）：faster-whisper（本地）或 openai-api

TTS 语音偏好：

# Edge-TTS 支持多种语音
"voice": {
  "tts": "edge-tts",
  "voices": ["zh-CN-XiaoxiaoNeural"]      # 中文女声（温暖）
}

6. Node Host 配置（nodes 区块）

"nodes": {
  "enabled": true,                       
  "tree": {
    "name": "树莓派集群",
    "host": "192.168.31.0/24"           
  },
  "devices": [                           
    {"id": "pi-1", "name": "树莓派", "ip": "192.168.31.230"},
    {"id": "pi-2", "name": "树莓派 2", "ip": "192.168.31.59"}
  ]
}

Node Host 功能：

• 通过局域网自动发现树莓派等远程节点
• 支持摄像头、屏幕录制等硬件功能
• host：DHCP 网段或固定 IP 范围

7. 记忆系统配置（memory 区块）

"memory": {
  "enabled": true,                      
  "dailyNotes": "./memory/",            
  "maxDailyDays": 365                   
}

说明：

• dailyNotes：每日笔记存放目录（相对路径）
• maxDailyDays：保留天数，防止磁盘爆满

批量模型切换

# 一键切换到云端模式（无本地模型时）
cat > ~/.openclaw/openclaw.json << 'EOF'
{
  "gateway": {"bind": "0.0.0.0:18789", "cors": true, "logLevel": "info"},
  "models": {
    "default": "zai/glm-5",
    "fallback": "moonshot/kimi-k2.5"
  },
  "proxy": {"http": "", "https": ""},
  "channels": {
    "telegram": {"enabled": true, "botToken": "xxx", "allowFrom": [6327632490]},
    "feishu": {"enabled": true, "appId": "cli_your_app_id"}
  },
  "voice": {"tts": "edge-tts", "stt": "faster-whisper"},
  "nodes": {"enabled": true, "tree": {"name": "节点集群", "host": "192.168.0.0/16"}},
  "memory": {"enabled": true, "dailyNotes": "./memory/", "maxDailyDays": 365}
}
EOF

openclaw gateway restart

自定义日志输出

# 将日志同时输出到文件和标准输出
"gateway": {
  "bind": "0.0.0.0:18789",
  "logFile": "./logs/gateway.log",      # 自定义日志文件路径
  "rotateDays": 7                        # 每 7 天滚动一次
}

禁用不需要的功能

# 最小化配置（仅保留核心功能）
{
  "gateway": {"bind": "127.0.0.1:18789", "cors": false, "logLevel": "error"},
  "models": {"default": "ollama/qwen3.5:9b"},
  "proxy": {"http": "", "https": ""},
  "channels": {"telegram": {"enabled": true, ...}},
  "nodes": {"enabled": false}            # 禁用 Node Host
}

敏感信息保护

• 切勿将配置文件提交到 Git：包含 botToken、AppSecret 等敏感信息
• 使用环境变量存储 Token：botToken=${BOT_TOKEN}
• 限制网络访问：通过防火墙只允许必要 IP 访问端口
• 定期轮换 API Token：每 90 天更新一次 Telegram Bot Token

服务文件安全设置

# 创建 systemd 服务文件
cat > ~/.config/systemd/user/openclaw-gateway.service << 'EOF'
[Unit]
Description=OpenClaw Gateway Service
After=network.target

[Service]
Type=simple
User=用户名               # 非 root 用户运行
WorkingDirectory=~/.openclaw
Environment="HTTP_PROXY=http://127.0.0.1:7897"
Environment="HTTPS_PROXY=http://127.0.0.1:7897"
ExecStart=openclaw gateway start
Restart=on-failure
RestartSec=10

[Install]
WantedBy=default.target
EOF

# 启用服务
systemctl --user enable openclaw-gateway.service
systemctl --user start openclaw-gateway.service

# 1. 编辑配置文件（备份前先查看）
cat ~/.openclaw/openclaw.json

# 2. 备份当前配置
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup.$(date +%Y%m%d)

# 3. 编辑配置
nano ~/.openclaw/openclaw.json
# 或 vim ~/.openclaw/openclaw.json

# 4. 验证 JSON 格式（防止语法错误）
python -m json.tool ~/.openclaw/openclaw.json

# 5. 重启服务
systemctl --user restart openclaw-gateway.service

# 6. 查看日志
journalctl --user-unit=openclaw-gateway.service -f

# 7. 回滚配置（如果需要）
mv ~/.openclaw/openclaw.json.backup.* ~/.openclaw/openclaw.json

• 服务状态检查：
  systemctl --user status openclaw-gateway.service
• 端口监听检查：
  ss -tlnp | grep 18789
• 代理连通性测试：
  curl -x http://127.0.0.1:7897 https://api.telegram.org/getMe
• 模型可用性检查：
  ollama list（本地模型）或查看 Gateway 日志
• 渠道连接测试：
  在 Telegram/飞书验证 bot 是否正常工作

问题：Gateway 无法启动

# 检查端口占用
ss -tlnp | grep 18789

# 检查服务日志
journalctl --user-unit=openclaw-gateway.service -n 50

# 查看配置文件语法
python -m json.tool ~/.openclaw/openclaw.json

问题：Telegram Bot 无响应

# 检查 bot 是否在线
curl https://api.telegram.org/bot<TOKEN>/getMe

# 重启服务后重新连接
systemctl --user restart openclaw-gateway.service

问题：模型调用超时

# 检查 Ollama 是否运行
systemctl --user status ollama.service

# 查看模型状态
ollama list

# 拉取缺失的模型
ollama pull qwen3.5:9b

• OpenClaw 官方文档
• GitHub 源码仓库
• 社区 Discord：https://discord.com/invite/clawd

通过本指南，你已经掌握了 openclaw.json 配置文件的完整知识体系：

• 基础设置：端口、日志级别、跨域配置
• 模型管理：本地优先 + 云端降级方案
• 网络代理：内网环境下的代理配置
• 多渠道接入：Telegram/飞书同时使用
• TTS/STT：语音功能优化配置
• 节点管理：树莓派等硬件集成
• 记忆系统：长期记忆存储方案
• 安全加固：Token 轮换、权限控制

🎯 OpenClaw 系列文章 03 | 最后更新：2026-03-16