OpenClaw 完全使用指南：从零搭建你的 AI 会话系统

写在前面#

这篇文章不是 OpenClaw 官方文档的翻译，而是基于我自己从零搭建、踩坑、调试后的完整实战总结。如果你也想用 OpenClaw 搭建一个稳定、可扩展、成本可控的 AI 会话系统，这篇文章应该能帮到你。

目标读者：

刚接触 OpenClaw 的新手
想理解配置逻辑、排查问题的用户
需要管理多个 AI 模型的人

阅读提示：建议配合终端实际操作，边读边敲命令，理解更深。

一、OpenClaw 是什么#

OpenClaw 是一个AI Gateway（AI 网关）——它位于你和各种 AI 模型之间，作为中间层统一管理：

多模型接入：OpenAI、Kimi、Claude、Qwen 等统一配置
会话管理：自动维护上下文、token 计算、历史记录
工具集成：内置搜索、文件读取、网页抓取等能力
多渠道支持：Telegram、Discord、Slack 等一键接入
智能路由：自动 fallback，一个模型挂了自动切另一个

为什么不用官方 SDK 直接调？#

方式	问题
官方 SDK	每个模型一套代码，切换模型改一堆东西
OpenClaw	配置里改一行，`openclaw gateway restart` 就生效

核心优势：配置驱动，一次设置，到处运行。

二、安装与初始化#

1. 安装 OpenClaw#

1
# 全局安装
2
npm i -g openclaw
3

4
# 验证安装
5
openclaw --version

2. 查看帮助#

1
# 查看所有命令
2
openclaw --help
3

4
# 查看具体命令帮助
5
openclaw gateway --help
6
openclaw configure --help

3. 初始化配置（ wizard 模式）#

1
openclaw configure

这个命令会启动交互式向导，引导你完成：

选择默认模型
配置 API Key
选择接入渠道（Telegram、Discord 等）
生成 ~/.openclaw/openclaw.json

什么时候需要重新运行 configure：

第一次安装后
配置文件损坏
想快速重置到默认配置

三、Gateway 核心命令（日常使用最高频）#

Gateway 是 OpenClaw 的核心进程，负责接收请求、路由到模型、管理会话。

查看 Gateway 状态#

1
openclaw gateway status

输出示例：

1
🦞 OpenClaw 2026.2.2-3
2
Gateway: running
3
Port: 18789
4
Mode: local
5
Uptime: 2h 15m

启动 Gateway#

1
# 前台启动（调试时看日志）
2
openclaw gateway start
3

4
# 后台启动（生产环境）
5
openclaw gateway start --daemon

停止 Gateway#

1
openclaw gateway stop

重启 Gateway（修改配置后必须做）#

1
openclaw gateway restart

⚠️ 重要提醒：

修改 openclaw.json 后 必须 restart
否则运行态还在用旧配置
旧 session 不会自动切换新模型

查看 Gateway 日志#

1
# 实时查看日志
2
openclaw gateway logs
3

4
# 查看最近 100 行
5
openclaw gateway logs --tail 100
6

7
# 查看包含错误的日志
8
openclaw gateway logs --grep error

四、配置管理命令#

查看当前配置#

1
openclaw config get

这会输出完整的 openclaw.json 内容，带格式和语法高亮。

查看配置结构（schema）#

1
openclaw config schema

适合想了解有哪些配置项可以用的场景。

应用完整配置（谨慎使用）#

1
openclaw config apply < config.json

这会完全替换现有配置，然后自动重启 Gateway。

⚠️ 警告：用之前先备份原配置！

1
# 备份
2
openclaw config get > backup.json
3

4
# 修改后应用
5
cat my-config.json | openclaw config apply

安全 patch（推荐）#

1
# 只修改部分配置
2
openclaw config patch --raw '{"agents":{"defaults":{"model":{"primary":"moonshot/kimi-k2.5"}}}}'

优势：

只改你指定的字段
其他配置保持不变
自动校验 JSON 语法
自动重启 Gateway

五、会话与会话管理#

查看当前会话状态#

1
openclaw session status

输出关键信息：

当前模型
使用的 API Key
Token 使用量（in/out）
上下文占用比例
Runtime 模式

列出所有活跃会话#

1
openclaw sessions list

查看会话历史#

1
# 查看当前会话最近 20 条消息
2
openclaw sessions history
3

4
# 查看指定会话
5
openclaw sessions history --session <session-key>
6

7
# 查看最近 50 条
8
openclaw sessions history --limit 50

向其他会话发送消息#

1
openclaw sessions send --session <session-key> "你好"

派生子 Agent（高级用法）#

1
openclaw sessions spawn --task "帮我分析这个日志文件" --agent coding-agent

会在后台启动一个独立的子会话执行任务，完成后结果回到主会话。

六、系统诊断与维护#

运行诊断检查#

1
openclaw doctor

会检查：

配置文件语法
API Key 有效性
Gateway 健康状态
网络连通性
权限问题

非交互式诊断（CI/CD 场景）#

1
openclaw doctor --non-interactive

查看系统状态#

1
openclaw status

更新 OpenClaw#

1
# 检查更新
2
openclaw update check
3

4
# 执行更新
5
openclaw update run

更新后会自动重启 Gateway。

七、核心配置详解（openclaw.json）#

理解了配置结构，才能真正掌控 OpenClaw。

配置文件位置#

1
~/.openclaw/openclaw.json

核心概念速查#

概念	说明	示例
Provider	服务提供商	moonshot, openai, qwen-portal
Model	具体模型	kimi-k2.5, gpt-4
Primary	默认主模型	moonshot/kimi-k2.5
Fallback	失败时自动降级	按顺序尝试
Session	一次对话上下文	包含历史消息
Agent	配置模板	defaults 是默认配置

最小可用配置示例#

1
{
2
  "models": {
3
    "mode": "merge",
4
    "providers": {
5
      "moonshot": {
6
        "baseUrl": "https://api.moonshot.cn/v1",
7
        "apiKey": "sk-your-key",
8
        "api": "openai-completions",
9
        "models": [
10
          {
11
            "id": "kimi-k2.5",
12
            "name": "Kimi 2.5",
13
            "contextWindow": 200000,
14
            "maxTokens": 8192
15
          }
16
        ]
17
      }
18
    }
19
  },
20
  "agents": {
21
    "defaults": {
22
      "model": {
23
        "primary": "moonshot/kimi-k2.5",
24
        "fallbacks": []
25
      }
26
    }
27
  },
28
  "channels": {
29
    "telegram": {
30
      "enabled": true,
31
      "botToken": "your-bot-token"
32
    }
33
  }
34
}

多 Provider 配置示例#

1
{
2
  "models": {
3
    "providers": {
4
      "moonshot": {
5
        "baseUrl": "https://api.moonshot.cn/v1",
6
        "apiKey": "sk-moonshot-key",
7
        "models": [{"id": "kimi-k2.5", "contextWindow": 200000}]
8
      },
9
      "openai": {
10
        "baseUrl": "https://api.openai.com/v1",
11
        "apiKey": "sk-openai-key",
12
        "models": [{"id": "gpt-4", "contextWindow": 128000}]
13
      },
14
      "qwen-portal": {
15
        "baseUrl": "https://portal.qwen.ai/v1",
16
        "apiKey": "qwen-oauth",
17
        "models": [{"id": "coder-model", "contextWindow": 128000}]
18
      }
19
    }
20
  }
21
}

Primary 与 Fallback 详解#

1
{
2
  "agents": {
3
    "defaults": {
4
      "model": {
5
        "primary": "qwen-portal/coder-model",
6
        "fallbacks": [
7
          "moonshot/kimi-k2.5",
8
          "openai/gpt-4"
9
        ]
10
      }
11
    }
12
  }
13
}

执行逻辑：

优先用 primary（Qwen Coder）
如果超时/报错，尝试 fallbacks[0]（Kimi 2.5）
还失败，尝试 fallbacks[1]（GPT-4）
全部失败才报错

八、模型切换实战#

场景一：临时切换（当前会话）#

在对话中直接说：

“切到 GPT-5” → 当前会话用 GPT-5
“切回 Kimi” → 切回 Kimi
“用 Qwen 写代码” → 临时切 Qwen

特点：只影响当前对话，不影响全局配置。

场景二：修改全局 Primary#

1
# 切到 Kimi 2.5
2
openclaw config patch --raw '{"agents":{"defaults":{"model":{"primary":"moonshot/kimi-k2.5"}}}}'
3

4
# 切到 Qwen Coder
5
openclaw config patch --raw '{"agents":{"defaults":{"model":{"primary":"qwen-portal/coder-model"}}}}'
6

7
# 切到 GPT-4
8
openclaw config patch --raw '{"agents":{"defaults":{"model":{"primary":"openai/gpt-4"}}}}'

场景三：查看当前在用哪个模型#

1
openclaw session status

关键字段：

Model：当前模型
api-key：用的哪个 provider

九、官方 API vs 中转 API#

这是新手最容易踩坑的地方。

区别对比#

维度	官方 API	中转 API
计费	直接走厂商账户	走中转账户
稳定性	高	依赖中转商
模型映射	透明	可能不透明
延迟	低	多一层代理
成本	固定	可能更便宜

如何确认自己走的是哪条路？#

方法一：看 session status

1
openclaw session status

api-key 显示 moonshot:default = 官方
api-key 显示 third-party:xxx = 中转

方法二：看控制台

Moonshot 控制台有 Usage 记录 = 官方
中转后台有请求记录 = 中转

常见误区：

“改了配置但控制台没扣钱，是不是没生效？”

真相：

可能是 Usage 延迟（5-15分钟）
可能是用的赠送额度
旧 session 还在用旧配置

验证方法：发一条明显会扣费的长请求，等几分钟看 Usage。

十、常见问题 & 排错清单#

问题一：改了配置没生效#

检查清单：

是否运行了 openclaw gateway restart？
是否在当前 session？（旧 session 继续用旧配置）
JSON 格式是否正确？（少个逗号都会导致 fallback）

诊断命令：

1
openclaw doctor
2
openclaw config get | jq .  # 检查 JSON 格式

问题二：Gateway 启动失败#

排查步骤：

看日志：openclaw gateway logs --tail 50
检查端口占用：lsof -i :18789
检查配置：openclaw doctor

问题三：模型响应慢/超时#

可能原因：

模型服务本身慢
网络问题
token 太长

解决方案：

检查 fallback 是否触发
临时切换到其他模型
压缩上下文（compact）

问题四：Token 消耗异常#

检查方法：

1
openclaw session status

看 Tokens 字段的 in/out。

优化建议：

长对话及时开启新 session
使用 compaction 模式
选择合适的模型（Qwen 免费，Kimi 性价比高）

十一、进阶技巧#

1. 快速备份配置#

1
# 备份
2
openclaw config get > openclaw-backup-$(date +%Y%m%d).json
3

4
# 恢复
5
cat backup.json | openclaw config apply

2. 查看版本信息#

1
openclaw --version
2
openclaw status

3. 多环境管理#

1
# 开发环境
2
export OPENCLAW_CONFIG=~/.openclaw/dev.json
3

4
# 生产环境
5
export OPENCLAW_CONFIG=~/.openclaw/prod.json

4. 配合 systemd 守护进程#

1
[Unit]
2
Description=OpenClaw Gateway
3
After=network.target
4

5
[Service]
6
Type=simple
7
User=your-user
8
ExecStart=/usr/bin/openclaw gateway start
9
Restart=always
10

11
[Install]
12
WantedBy=multi-user.target

十二、写在最后#

OpenClaw 的精髓在于配置驱动。理解 provider → model → primary → fallback 这条链，你就掌握了它的核心逻辑。

建议的搭建顺序：

跑通 openclaw configure
配置一个官方 Provider（如 Moonshot）
测试 openclaw gateway status 正常
接入一个渠道（如 Telegram）
逐步添加 fallback 和工具

遇到问题，优先运行 openclaw doctor，80% 的问题都能定位。

祝搭建顺利，享受你的 AI 助手 🐕

参考链接#

OpenClaw 官方文档：https://docs.openclaw.ai
GitHub 仓库：https://github.com/openclaw/openclaw
Moonshot API 文档：https://platform.moonshot.cn
Qwen Portal：https://portal.qwen.ai

文章信息

作者：基于真实踩坑经验整理
发布时间：2026-02-07
字数：约 5500 字
适用版本：OpenClaw 2026.2.x

Syndred's Home