一、准备工作：安装基础环境
OpenClaw运行依赖Node.js 24+ 和 Git。
1. Node.js 安装
brew install node
brew link node --overwrite --force
# 配置npm淘宝镜像
npm config set registry https://registry.npmmirror.com/
2. Git 安装
# macOS
brew install git
3. 安装后验证（必做，确认环境生效）
# 验证Node.js
node -v
# 验证npm
npm -v
# 验证Git
git --version
二、OpenClaw 安装步骤
curl -fsSL https://openclaw.ai/install.sh | bash
这条命令会装 CLI 并自动启动新手引导（onboard）。
手动引导（之后随时可以跑）：
# 运行初始化向导
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 状态、配置有没有问题。有红色报错就按提示修，黄色警告可以先忽略。
(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，完成提供商基础配置：
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 默认的智能交互模型，后续可根据需求切换：
openclaw config set agents.defaults.model.primary "deepseek/deepseek-chat"
3.4 创建模型别名（可选）
为模型创建简短别名，简化后续模型切换命令，提升使用效率：
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 查看模型配置状态
确认默认模型与已配置模型列表是否正确：
(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的方式
在终端执行以下命令，获取网关令牌：
openclaw config get gateway.auth.token
或者直接查看配置文件：
grep -A1 '"token"' ~/.openclaw/openclaw.json
五、OpenClaw 常用管理命令
5.1 服务管理
# 启动 Gateway 服务
openclaw gateway
# 重启 Gateway 服务
openclaw gateway restart
# 停止 Gateway 服务
openclaw gateway stop
# 查看基础服务状态
openclaw status
# 查看详细服务状态
openclaw status --all
# 查看实时运行日志
openclaw logs --follow
5.2 模型管理
# 列出所有可用模型
openclaw models list --all
# 查看当前模型配置状态
openclaw models status
# 聊天中快速切换模型（终端/飞书均可）
/model 模型别名（如 deepseek-v3）
# 重新设置默认模型
openclaw config set agents.defaults.model.primary "模型ID"
# 查看所有模型别名
openclaw models aliases list
5.3 对话交互
# 终端发送单条测试消息
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 配置管理
# 查看指定路径的配置
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：
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 并重启服务：
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），提升服务可用性：
openclaw config set agents.defaults.model.fallbacks '["deepseek/deepseek-reasoner"]'
