OpenClaw 从零到一

预计用时：15 分钟 | 前置条件：已完成 Codex CLI 安装

什么是 OpenClaw

OpenClaw 是一个开源的 AI 网关（Gateway）。你可以把它理解成一个"AI 管家"——它在后台常驻运行，帮你把各种 AI 大模型（ChatGPT、Claude、Gemini 等）连接到你日常使用的通讯工具上。

它能做什么：

通过 Telegram / Discord / WhatsApp / 飞书 随时和 AI 对话
拥有长期记忆，记住你说过的话和偏好
支持技能市场，可以安装各种插件扩展功能
完全运行在你自己的电脑上，数据不经过第三方

简单来说：装好 OpenClaw，你就拥有了一个 24 小时在线的私人 AI 助手。

前置条件

在开始之前，确认你已经完成了以下准备：

检查项	怎么验证
Node.js v22 或更高	终端输入 `node --version`，看到 `v22.x.x` 或更高
npm 已安装	终端输入 `npm --version`，能看到版本号
Codex CLI 已安装	终端输入 `codex --version`，能看到版本号
ChatGPT Plus 订阅	你的 OpenAI 账号是 Plus 或 Pro 会员

如果 Node.js 版本不够，先安装：

code

brew install node@22
brew link --overwrite node@22

安装完后重新打开一个终端窗口，再用 node --version 确认版本。

安装方式一：一键安装（推荐）

这是最简单的方式。打开终端，粘贴这一行命令：

code

curl -fsSL https://raw.githubusercontent.com/miaoxworld/OpenClawInstaller/main/install.sh | bash

安装脚本会自动完成以下事情：

检测你的系统环境
安装 OpenClaw CLI 工具
引导你完成核心配置（选择 AI 模型、填写身份信息）
测试 API 连接是否正常
启动后台服务
可选：打开配置菜单做进一步设置

安装过程中会问你几个问题（选择模型、输入信息等），按照提示一步步来就行。不确定选什么的时候，直接按回车用默认值。

安装脚本跑完后，跳到下面的 "配置 Codex OAuth 作为大脑" 这一节继续。

安装方式二：手动安装

如果一键安装脚本出了问题，或者你更喜欢自己掌控每一步，可以手动安装。

第一步：安装 CLI 工具

code

npm install -g openclaw

安装过程中可能会看到一些 deprecated 警告，这是正常的，不影响使用。只要最后没有红色的 ERR! 就没问题。

第二步：运行配置向导

code

openclaw onboard --install-daemon

这个命令会启动一个交互式向导，引导你完成所有配置。它会：

创建配置目录 ~/.openclaw/
让你选择 AI 模型提供商
设置身份信息
安装后台守护进程（daemon），让 OpenClaw 开机自动运行

注意：openclaw onboard 是交互式命令，必须在终端手动执行，不能通过脚本自动化。

配置 Codex OAuth 作为大脑

这是整个安装过程中最关键的一步。OpenClaw 本身只是一个"网关"，它需要连接一个 AI 模型才能工作。我们推荐使用 OpenAI Codex 作为它的"大脑"。

为什么选 Codex OAuth

不需要单独购买 API Key。如果你有 ChatGPT Plus 订阅（$20/月），Codex 是免费附赠的
无需管理余额。不像 API Key 那样需要充值、担心额度用完
模型质量高。Codex 背后跑的是 OpenAI 最新的模型

配置步骤

如果你在安装向导中已经选择了 OpenAI Codex 作为模型，这一步可以跳过。否则，手动执行：

code

openclaw models auth login --provider openai-codex

执行后会发生这些事情：

终端会输出一条提示，告诉你浏览器即将打开
浏览器自动打开 OpenAI 的授权页面
用你的 OpenAI 账号登录并点击"授权"
浏览器会跳转到一个 localhost 开头的地址（看起来像是加载失败的空白页，这是正常的）
复制浏览器地址栏里的完整 URL，粘贴回终端
按回车，终端显示授权成功

验证授权是否成功

code

openclaw doctor

如果看到模型相关的检查项全部通过（绿色对号），说明配置成功了。

Token 会过期吗

会，大约每 10 天需要重新授权一次。到时候 OpenClaw 会提醒你，重新跑一遍 openclaw models auth login --provider openai-codex 就行。

健康检查

安装完成后，运行一次全面检查：

code

openclaw doctor --fix

--fix 参数会自动修复它能发现的问题。如果一切正常，你会看到所有检查项都是绿色的。

如果有红色的报错，看看是不是下面这些常见问题：

报错信息	原因	解决方法
`gateway.mode` 未设置	配置文件缺少必要字段	`openclaw config set gateway.mode local`
Sessions 目录缺失	初始化不完整	`openclaw setup`
Node.js 版本不够	系统 Node.js 太旧	`brew install node@22 && brew link --overwrite node@22`

第一次对话

一切就绪，试试和你的 AI 助手说句话。

如果 OpenClaw 的后台服务已经在运行（一键安装会自动启动），你可以直接在终端输入：

code

openclaw chat

然后输入任何问题，比如"你好，你是谁？"。如果 AI 回复了你，恭喜——安装成功了。

如果服务还没启动，先手动启动：

code

openclaw gateway start

然后再试 openclaw chat。

排错指南

问题 1：输入命令后提示 "command not found"

说明 OpenClaw 没装上或者 PATH 不对。试试：

code

# 确认安装了没
npm list -g openclaw
 
# 如果没装上，重新安装
npm install -g openclaw

如果安装了但还是找不到命令，关掉终端重新打开一个。

问题 2：gateway.mode 未设置

这是最常见的问题。执行：

code

openclaw config set gateway.mode local

问题 3：对话卡住没有回复

可能是 session 数据库损坏了。执行以下步骤：

code

# 停止服务
openclaw gateway stop
 
# 删除损坏的数据库文件
rm ~/.openclaw/main.sqlite
 
# 重新启动
openclaw gateway start

问题 4：Codex 授权失败

确保：

你的 OpenAI 账号是 Plus 或 Pro 订阅
浏览器登录的是正确的 OpenAI 账号
复制的 URL 是完整的（从 http://localhost 开始到最后）

关键文件一览

安装完成后，OpenClaw 的所有数据都在 ~/.openclaw/ 目录下：

文件 / 目录	用途
`openclaw.json`	核心配置文件。模型选择、渠道配置、技能设置都在这里
`workspace/SOUL.md`	AI 的"人设"文件。你可以编辑它来自定义 AI 的性格和行为
`env`	环境变量文件。存放 API Key 等敏感信息，绝不要上传到 Git
`logs/`	日志目录。排查问题时可以看 `gateway.err.log`
`main.sqlite`	对话数据库。如果 session 卡死，删掉这个文件重启即可
`backups/`	配置自动备份

其中 env 文件包含你的 API Key 等敏感信息。千万不要把 ~/.openclaw/ 整个目录上传到 GitHub 或发给别人。

常用命令速查

code

# 服务管理
openclaw gateway start      # 启动后台服务
openclaw gateway stop       # 停止服务
openclaw gateway restart    # 重启服务
openclaw gateway status     # 查看运行状态
 
# 诊断
openclaw doctor             # 检查安装状态
openclaw doctor --fix       # 自动修复问题
openclaw logs --follow      # 实时查看日志
 
# 配置
openclaw config             # 打开配置文件
openclaw onboard            # 重新运行配置向导
bash ~/.openclaw/config-menu.sh  # 打开配置菜单

下一步

OpenClaw 已经在你的电脑上跑起来了。但现在它只能在终端里对话，还不够方便。

下一步，我们把它连接到 Telegram，这样你用手机就能随时和 AI 聊天。

连接 Telegram Bot -->