OpenClaw 小白基础配置

OpenClaw 是一个可以在本地项目里使用的 AI 编程工具。你可以让它阅读项目、解释代码、修改文件、运行命令，也可以把它当成一个命令行里的开发助手。

本教程面向第一次使用 OpenClaw 的新手，目标是让你完成三件事：

• 安装 OpenClaw
• 配置 API Key、接口地址和模型
• 在当前项目里跑通第一次对话

关于密钥

API Key 是你的账号凭证，不要发给别人，也不要提交到 GitHub。教程里的示例值需要换成你自己的真实配置。

---

一、使用前准备

1. 完成基础环境安装

OpenClaw 官方建议使用 Node.js 24，Node.js 22.19+ 也支持。第一次配置前，建议先完成：

使用前环境配置

确认下面命令都能看到版本号：

node -v
npm -v
git --version

如果其中某个命令提示不存在，先回到环境配置章节安装对应工具。

2. 准备 API Key

进入 coding-play.codes 控制台，打开 API 密钥 页面，创建一个专门给 OpenClaw 使用的密钥。

建议命名为：

openclaw

这样后续查看使用记录、排查额度消耗时更容易区分。

3. 准备接口信息

配置 OpenClaw 前，需要准备三类信息：

配置项	说明
API Key	在 coding-play.codes 的 API 密钥页面创建并复制
Base URL	按后台或服务商提供的 OpenAI 兼容接口地址填写
模型名称	按模型列表或后台展示的模型名称填写

常见字段名称可能会写成：

• apiKey
• baseUrl
• model
• provider

只要含义一致，填入对应位置即可。

---

二、安装 OpenClaw

OpenClaw 推荐使用官方安装脚本。

macOS / Linux / WSL2

curl -fsSL https://openclaw.ai/install.sh | bash

Windows PowerShell

iwr -useb https://openclaw.ai/install.ps1 | iex

如果你已经自己管理 Node.js，也可以使用 npm 安装：

npm install -g openclaw@latest

安装完成后，检查命令是否可用：

openclaw --version

如果能看到版本号，说明安装成功。

也可以顺手做一次诊断：

openclaw doctor

推荐新手使用安装脚本

安装脚本会自动处理常见环境问题。手动 npm 安装更适合已经熟悉 Node.js 全局包管理的用户。

---

三、使用向导配置

OpenClaw 可以通过初始化向导完成基础配置。

在终端执行：

openclaw onboard --install-daemon

根据提示依次填写：

提示项	应该填写什么
Provider	选择自定义 OpenAI 兼容服务，或选择和后台说明一致的服务商
API Key	粘贴你在 coding-play.codes 创建的 API Key
Base URL	填写后台提供的接口地址
Model	填写你要使用的模型名称

如果向导让你选择默认模型，建议先选一个通用编程模型。等基础配置跑通后，再根据任务切换更强或更便宜的模型。

配置完成后，可以检查 Gateway 是否运行：

openclaw gateway status

也可以打开控制台页面：

openclaw dashboard

如果浏览器能打开控制台，并且聊天能正常回复，说明基础配置已经生效。

---

四、手动配置思路

如果你的 OpenClaw 版本没有向导，或者向导配置失败，可以按工具提示找到配置文件，再手动写入配置。

常见配置会包含这些内容：

{
  "provider": "openai-compatible",
  "apiKey": "你的 API Key",
  "baseUrl": "你的 Base URL",
  "model": "你的模型名称"
}

需要替换的地方：

• 你的 API Key：换成 coding-play.codes 后台创建的密钥
• 你的 Base URL：换成后台提供的接口地址
• 你的模型名称：换成后台模型列表里的真实名称

不要盲目复制路径

OpenClaw 不同版本的配置文件路径可能不同。优先以命令行提示、官方文档或当前版本输出为准。

---

五、第一次运行

进入你想让 OpenClaw 处理的项目目录：

cd ~/Desktop/my-project

然后启动 OpenClaw：

openclaw

第一次可以先问一个不会改代码的问题：

请先阅读当前项目，不要修改文件，告诉我这个项目的技术栈、启动命令和主要目录结构。

如果它能正常读取项目并回答，说明基础配置已经跑通。

---

六、新手常用问法

了解项目

请分析当前项目结构，并告诉我每个主要目录是做什么的。

修改文档

帮我新增一篇工具配置教程，并把左侧菜单入口也加上。

排查报错

我运行 npm run dev 报错了，请先定位原因，再给出修复方案。

修改前先确认

请先给我一个修改计划，不要直接改文件。等我确认后再执行。

---

七、常见问题

1. 提示 API Key 无效

优先检查：

• API Key 是否复制完整
• 是否多复制了空格或换行
• 是否使用了已经删除或禁用的密钥
• 当前工具配置的服务商是否和 Base URL 匹配

2. 提示模型不存在

优先检查：

• 模型名称是否和后台显示完全一致
• 是否把显示名当成了模型 ID
• 当前账号是否有这个模型的使用权限

3. 请求一直失败

优先检查：

• 账户余额是否充足
• Base URL 是否填写完整
• 网络是否能访问对应接口
• 当前 OpenClaw 版本是否支持自定义接口

4. 不想让它乱改文件

第一次使用时，建议明确告诉它：

先只阅读和分析，不要修改任何文件。

等你确认方案后，再让它执行修改。