OpenClaw 配置指南

AI 网关 + Telegram Bot 的完整配置手册

架构概览

code

┌─────────────────────────────────────────────────────┐
│                    OpenClaw Gateway                  │
│              (localhost:18789, token auth)           │
├─────────────┬───────────────┬──────────────────────┤
│  Telegram   │   Plugins     │       Skills (14)     │
│  Bot 频道   │  lobster      │  apple-notes, whisper │
│             │  llm-task     │  summarize, nano-pdf  │
│             │  copilot-proxy│  video-frames, ...    │
├─────────────┴───────────────┴──────────────────────┤
│                   模型路由层                         │
│  Primary: M2.5 (本地 oMLX)  →  Fallback: Cloud     │
└──────────────────────────────────────────────────────┘

OpenClaw 是一个多通道 AI 网关，核心能力：

Telegram Bot — 通过 Telegram 与 AI 对话
插件系统 — 扩展功能（lobster 巡检、copilot-proxy 等）
技能框架 — 14 个已就绪技能（Apple Notes、Whisper 语音转文字等）
记忆系统 — qmd 后端，BM25 + 向量搜索 + Reranking

一、openclaw.json 核心配置

配置文件位置：~/.openclaw/openclaw.json

模型配置

code

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "ollama//Users/neo/models/MiniMax-M2.5-MLX-8bit",
        "fallback": "openai-codex/gpt-5.3-codex"
      },
      "timeoutSeconds": 120,
      "reasoning": true,
      "stream": false
    }
  }
}

字段	说明
`primary`	主模型，指向本地 oMLX
`fallback`	备用模型，本地超时后自动切换
`timeoutSeconds`	本地推理超时（120 秒后 fallback）
`stream`	关闭流式（防止工具调用名称损坏）

切换主模型

code

# 切换到本地 M2.5
openclaw config set agents.defaults.model.primary \
  "ollama//Users/neo/models/MiniMax-M2.5-MLX-8bit"
 
# 切换到云端
openclaw config set agents.defaults.model.primary \
  "openai-codex/gpt-5.3-codex"

二、Telegram Bot 配置

基本设置

code

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "YOUR_BOT_TOKEN",
      "dm": { "strategy": "pairing" },
      "groups": { "strategy": "allowlist" },
      "streaming": "partial"
    }
  }
}

配对新用户

Telegram Bot 使用配对码认证。新用户首次发消息时，Bot 会返回配对码：

code

# 在终端审批配对
openclaw pairing approve telegram <配对码>
 
# 查看已配对用户
openclaw pairing list

自定义命令

code

/note — 快速记笔记（调用 apple-notes 技能）
/remind — 设置提醒（调用 apple-reminders 技能）
/status — 查看系统状态
/weather — 天气查询
/summarize — URL/YouTube 摘要

三、qmd 记忆系统

OpenClaw 使用 qmd 作为记忆后端，支持 BM25 + 向量搜索 + Reranking。

配置

code

{
  "memory": {
    "backend": "qmd",
    "workspace": "~/.openclaw/workspace"
  }
}

索引内容

qmd 自动索引以下文件：

~/.openclaw/workspace/MEMORY.md — 重要决策和任务
~/.openclaw/workspace/memory/**/*.md — 每日记忆
会话转录（sessions.enabled: true）

首次使用

code

# qmd 通过 bun 全局安装
bun install -g qmd
 
# 首次搜索会自动下载 GGUF 模型（~0.6GB）
# 包括 embedding 模型和 reranker 模型

四、技能框架

已就绪技能（14/49）

技能	工具	功能
apple-notes	`memo`	管理 Apple 备忘录
apple-reminders	`remindctl`	管理 Apple 提醒事项
clawhub	`clawhub`	技能市场搜索/安装
coding-agent	内置	运行编码代理
github	`gh`	GitHub Issues/PR/CI
healthcheck	内置	安全审计与加固
nano-pdf	`nano-pdf`	自然语言编辑 PDF
openai-whisper	`whisper`	本地语音转文字
session-logs	`jq`	搜索历史会话日志
skill-creator	内置	创建自定义技能
summarize	`summarize`	URL/YouTube 摘要
tmux	`tmux`	远程控制终端
video-frames	`ffmpeg`	视频帧提取
weather	内置	天气查询

安装新技能

code

# 从 ClawHub 搜索
clawhub search <关键词>
 
# 安装
clawhub install <技能名>
 
# 查看已安装技能
openclaw skills list

五、插件配置

已启用插件

插件	功能
`telegram`	Telegram 机器人通道
`lobster`	增强对话管理
`llm-task`	LLM 任务调度
`copilot-proxy`	多模型代理（13 个模型）

Compaction 与记忆刷写

code

{
  "compaction": {
    "mode": "safeguard"
  },
  "memoryFlush": {
    "enabled": true
  }
}

上下文压缩前自动保存重要对话到 memory 文件。

六、Cron 定时任务

龙虾巡检（Lobster Patrol）

每天 12 次深度巡检，通过 Claude Code Agent 执行：

code

# 手动触发
ai-patrol
 
# 在 Claude Code 中
/lobster

巡检内容：

所有 AI 服务状态
模型健康度
系统资源（内存、CPU、磁盘）
日志异常分析

Codex OAuth 刷新

OAuth token 有效期约 10 天，过期后需要刷新：

code

openclaw models auth login --provider openai-codex

七、日常操作速查

code

# 启动/停止
openclaw start
openclaw stop
 
# 状态检查
openclaw status
 
# 全面诊断
openclaw doctor --fix
 
# 查看日志
openclaw logs
 
# 更新 OpenClaw
npm update -g openclaw

八、排错指南

Gateway 每 11 秒重启

code

# 原因：auth token 未配置
openclaw config set gateway.auth.mode token
openclaw config set gateway.auth.token "$(openssl rand -hex 24)"

模型返回 HuggingFace 404

原因：Model ID 与 oMLX 实际加载的模型路径不匹配。确保 openclaw.json 中的 model ID 与 oMLX 启动参数一致。

Telegram Bot 不响应

code

# 1. 检查 OpenClaw 运行状态
openclaw status
 
# 2. 检查用户是否已配对
openclaw pairing list
 
# 3. 检查推理引擎
curl http://localhost:8000/v1/models

降级模式（68ms 完成）

如果 OpenClaw 在 68ms 内就返回响应，说明进入了降级模式。清除 sqlite 缓存并重启：

code

openclaw stop
rm ~/.openclaw/data/*.sqlite
openclaw start

九、关键文件

文件	用途
`~/.openclaw/openclaw.json`	主配置文件
`~/.openclaw/workspace/SOUL.md`	AI 灵魂文件（行为准则）
`~/.openclaw/workspace/MEMORY.md`	重要决策和任务
`~/.openclaw/workspace/memory/`	每日记忆
`~/.openclaw/credentials/`	各 provider 认证信息

OpenClaw 是 AIOS 的 AI 网关层，连接 Telegram、推理引擎和记忆系统。配好后基本不需要再动。