OpenClaw 初学者必看指南

一、准备工作：安装基础环境

OpenClaw运行依赖Node.js 24+ 和 Git。

1. Node.js 安装

bash 复制代码

brew install node
brew link node --overwrite --force

# 配置npm淘宝镜像
npm config set registry https://registry.npmmirror.com/

2. Git 安装

bash 复制代码

# macOS
brew install git

3. 安装后验证（必做，确认环境生效）

bash 复制代码

# 验证Node.js
node -v
# 验证npm
npm -v
# 验证Git
git --version

二、OpenClaw 安装步骤

arduino 复制代码

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

这条命令会装 CLI 并自动启动新手引导（onboard）。

手动引导（之后随时可以跑）：

bash 复制代码

# 运行初始化向导
openclaw onboard

安装完成后自动进入交互式配置流程，按以下选项选择即可，部分配置可后续在Web UI/终端修改，配置项后附简单说明，方便理解选择原因：

配置项	选择/操作	配置说明
I understand this is powerful and inherently risky. Continue?	选择 "Yes"	确认知晓风险并继续部署
Onboarding mode	选择 "QuickStart"	快速启动模式，适合新手，简化配置
Model/auth provider	选免费Qwen / 选"Skip for now"	推荐先选Qwen（免费），后续可配置火山引擎等其他模型；暂不配置则选Skip
Filter models by provider	选择 "All providers"	显示所有模型提供商，方便后续切换
Default model	使用默认配置	保持默认，后续可在配置文件中修改
Select channel (QuickStart)	选择 "Skip for now"	暂不配置渠道
Configure skills now? (recommended)	选择 "No"	暂不配置技能，后续按需添加
Enable hooks?	按空格键选中 → 按回车键下一步	启用钩子功能，支持命令日志、会话记忆等核心特性
How do you want to hatch your bot?	选择 "Hatch in TUI"	从终端界面启动机器人，基础交互更便捷

复制代码

openclaw doctor

这条命令会检查环境依赖、Gateway 状态、配置有没有问题。有红色报错就按提示修，黄色警告可以先忽略。

vbnet 复制代码

(base)  evan  ~  openclaw --version

OpenClaw 2026.3.13 (61d171a)
(base)  evan  ~  openclaw status


🦞 OpenClaw 2026.3.13 (61d171a) --- Making 'I'll automate that later' happen now.

│
◇
│
◇
OpenClaw status

Overview
┌─────────────────┬────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ Item            │ Value                                                                                                                      │
├─────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Dashboard       │ http://127.0.0.1:18789/                                                                                                    │
│ OS              │ macos 15.0.1 (x64) · node 24.14.0                                                                                          │
│ Tailscale       │ off                                                                                                                        │
│ Channel         │ stable (default)                                                                                                           │
│ Update          │ pnpm · npm latest 2026.3.13                                                                                                │
│ Gateway         │ local · ws://127.0.0.1:18789 (local loopback) · unreachable (missing scope: operator.read)                                 │
│ Gateway service │ LaunchAgent installed · loaded · running (pid 45923)                                                                       │
│ Node service    │ LaunchAgent not installed                                                                                                  │
│ Agents          │ 1 · no bootstrap files · sessions 2 · default main active 20m ago                                                          │
│ Memory          │ 0 files · 0 chunks · dirty · sources memory · plugin memory-core · vector ready · fts ready · cache on (0)                 │
│ Probes          │ skipped (use --deep)                                                                                                       │
│ Events          │ none                                                                                                                       │
│ Heartbeat       │ 30m (main)                                                                                                                 │
│ Sessions        │ 2 active · default deepseek-chat (200k ctx) · ~/.openclaw/agents/main/sessions/sessions.json                               │
└─────────────────┴────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

Security audit
Summary: 0 critical · 2 warn · 1 info
  WARN Reverse proxy headers are not trusted
    gateway.bind is loopback and gateway.trustedProxies is empty. If you expose the Control UI through a reverse proxy, configure trusted proxies so local-client c...
    Fix: Set gateway.trustedProxies to your proxy IPs or keep the Control UI local-only.
  WARN Some gateway.nodes.denyCommands entries are ineffective
    gateway.nodes.denyCommands uses exact node command-name matching only (for example `system.run`), not shell-text filtering inside a command payload. - Unknown ...
    Fix: Use exact command names (for example: canvas.present, canvas.hide, canvas.navigate, canvas.eval, canvas.snapshot, canvas.a2ui.push, canvas.a2ui.pushJSONL, canvas.a2ui.reset). If you need broader restrictions, remove risky command IDs from allowCommands/default workflows and tighten tools.exec policy.
Full report: openclaw security audit
Deep probe: openclaw security audit --deep

Channels
┌─────────────────┬─────────┬────────┬─────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ Channel         │ Enabled │ State  │ Detail                                                                                                  │
├─────────────────┼─────────┼────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ openclaw-weixin │ ON      │ OK     │ token unknown (94d1...62d9 · len 58) · accounts 1/1                                                       │
└─────────────────┴─────────┴────────┴─────────────────────────────────────────────────────────────────────────────────────────────────────────┘

Sessions
┌──────────────────────────────────────────────────────────────────────────┬────────┬─────────┬───────────────┬────────────────────────────────┐
│ Key                                                                      │ Kind   │ Age     │ Model         │ Tokens                         │
├──────────────────────────────────────────────────────────────────────────┼────────┼─────────┼───────────────┼────────────────────────────────┤
│ agent:main:openclaw-weixin:dire...                                         │ direct │ 20m ago │ deepseek-chat │ 11k/200k (5%) · 🗄️ 97% cached  │
│ agent:main:main                                                          │ direct │ 21m ago │ deepseek-chat │ 47k/200k (23%) · 🗄️ 98% cached │
└──────────────────────────────────────────────────────────────────────────┴────────┴─────────┴───────────────┴────────────────────────────────┘

FAQ: https://docs.openclaw.ai/faq
Troubleshooting: https://docs.openclaw.ai/troubleshooting

Next steps:
  Need to share?      openclaw status --all
  Need to debug live? openclaw logs --follow
  Fix reachability first: openclaw gateway probe

三、DeepSeek 官方 API 配置流程

完成 OpenClaw 基础部署后，配置 DeepSeek API 作为智能交互的模型提供商，支持 DeepSeek Chat V3、DeepSeek Reasoner R1 等模型。

3.1 获取 DeepSeek API Key

访问 DeepSeek 官方平台，完成注册与账号验证；
进入平台「API 密钥」模块，创建并获取 API Key，格式为 sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx；
妥善保存 API Key，避免泄露（后续配置需直接使用）。

3.2 配置 DeepSeek 模型提供商

执行以下命令，将你的API_KEY替换为实际获取的 DeepSeek API Key，完成提供商基础配置：

vbnet 复制代码

openclaw config set models.providers.deepseek '{
  "baseUrl": "https://api.deepseek.com/v1",
  "apiKey": "你的API_KEY",
  "api": "openai-completions",
  "models": [
    {
      "id": "deepseek-chat",
      "name": "DeepSeek Chat (V3)"
    },
    {
      "id": "deepseek-reasoner",
      "name": "DeepSeek Reasoner (R1)"
    }
  ]
}'

3.3 设置默认交互模型

指定 deepseek-chat 为 OpenClaw 默认的智能交互模型，后续可根据需求切换：

arduino 复制代码

openclaw config set agents.defaults.model.primary "deepseek/deepseek-chat"

3.4 创建模型别名（可选）

为模型创建简短别名，简化后续模型切换命令，提升使用效率：

csharp 复制代码

openclaw models aliases add deepseek-v3 "deepseek/deepseek-chat"
openclaw models aliases add deepseek-r1 "deepseek/deepseek-reasoner"

3.5 重启 Gateway 服务使配置生效

复制代码

openclaw gateway restart

3.6 DeepSeek 配置测试与验证

3.6.1 查看模型配置状态

确认默认模型与已配置模型列表是否正确：

bash 复制代码

(base)  evan  ~  openclaw models status



🦞 OpenClaw 2026.3.13 (61d171a) --- Less clicking, more shipping, fewer "where did that file go" moments.

Config        : ~/.openclaw/openclaw.json
Agent dir     : ~/.openclaw/agents/main/agent
Default       : deepseek/deepseek-chat
Fallbacks (1) : qwen-portal/vision-model
Image model   : -
Image fallbacks (0): -
Aliases (3)   : qwen -> qwen-portal/coder-model, deepseek-v3 -> deepseek/deepseek-chat, deepseek-r1 -> deepseek/deepseek-reasoner
Configured models (4): qwen-portal/coder-model, qwen-portal/vision-model, deepseek/deepseek-chat, deepseek/deepseek-reasoner

Auth overview
Auth store    : ~/.openclaw/agents/main/agent/auth-profiles.json
Shell env     : off
Providers w/ OAuth/tokens (1): qwen-portal (1)
- deepseek effective=models.json:sk-360ba...9667dcca | models.json=sk-360ba...9667dcca | source=models.json: ~/.openclaw/agents/main/agent/models.json
- openai effective=env:be057974...LYuSycmF | env=be057974...LYuSycmF | source=env: OPENAI_API_KEY
- qwen-portal effective=profiles:~/.openclaw/agents/main/agent/auth-profiles.json | profiles=1 (oauth=1, token=0, api_key=0) | qwen-portal:default=OAuth | models.json=marker(qwen-oauth) | source=models.json: ~/.openclaw/agents/main/agent/models.json

OAuth/token status
- qwen-portal
  - qwen-portal:default ok expires in 0m

3.6.2 打开 Web 控制面板

通过可视化面板管理 OpenClaw，命令执行后将自动在浏览器打开面板：

复制代码

openclaw dashboard

获取token的方式

在终端执行以下命令，获取网关令牌：

arduino 复制代码

openclaw config get gateway.auth.token

或者直接查看配置文件：

javascript 复制代码

grep -A1 '"token"' ~/.openclaw/openclaw.json

五、OpenClaw 常用管理命令

5.1 服务管理

python 复制代码

# 启动 Gateway 服务
openclaw gateway
# 重启 Gateway 服务
openclaw gateway restart
# 停止 Gateway 服务
openclaw gateway stop
# 查看基础服务状态
openclaw status
# 查看详细服务状态
openclaw status --all
# 查看实时运行日志
openclaw logs --follow

5.2 模型管理

bash 复制代码

# 列出所有可用模型
openclaw models list --all
# 查看当前模型配置状态
openclaw models status
# 聊天中快速切换模型（终端/飞书均可）
/model 模型别名（如 deepseek-v3）
# 重新设置默认模型
openclaw config set agents.defaults.model.primary "模型ID"
# 查看所有模型别名
openclaw models aliases list

5.3 对话交互

bash 复制代码

# 终端发送单条测试消息
openclaw agent --session-id 会话ID --message "你的问题"
# 指定消息超时时间（单位：秒，示例为60秒）
openclaw agent --session-id test --message "问题" --timeout 60
# 本地模式交互（不通过 Gateway 服务）
openclaw agent --local --session-id test --message "问题"

5.4 配置管理

bash 复制代码

# 查看指定路径的配置
openclaw config get 配置路径
# 设置指定路径的配置
openclaw config set 配置路径 "值"
# 删除指定路径的配置
openclaw config unset 配置路径
# 重新运行交互式配置向导
openclaw configure

六、常见故障排除

6.1 DeepSeek API 相关问题

问题 1：Gateway Token 错误，提示「unauthorized: gateway token missing」

解决方法：通过命令打开带 Token 的 Web 控制面板，自动携带有效 Token：

复制代码

openclaw dashboard

或手动获取 Token：

arduino 复制代码

openclaw config get gateway.auth.token

问题 2：提示「Unknown model: xxx」，模型不可用

解决方法：

检查模型配置是否正确：openclaw models status
确认模型 ID 无误：openclaw models list --all | grep deepseek
重启 Gateway 服务：openclaw gateway restart

问题 3：提示「HTTP 401/Unauthorized」，API Key 无效

解决方法：

验证 DeepSeek 平台的 API Key 是否正确、未过期；
重新配置 API Key 并重启服务：

arduino 复制代码

openclaw config set models.providers.deepseek.apiKey "新的API_KEY"
openclaw gateway restart

问题 4：提示「Request timed out/No reply from agent」，连接超时

解决方法：

检查网络是否能正常访问 DeepSeek API：curl -I https://api.deepseek.com/v1/models
增加消息超时时间：openclaw agent --session-id test --message '测试' --timeout 120

问题 5：配置模型自动降级

设置备用模型，当主模型（如 deepseek-chat）不可用时，自动切换到备用模型（如 deepseek-reasoner），提升服务可用性：

arduino 复制代码

openclaw config set agents.defaults.model.fallbacks '["deepseek/deepseek-reasoner"]'