openclaw安装记录

标题

1、安装
- [1.1 安装node](#1.1 安装node)
- [1.2 安装openclaw](#1.2 安装openclaw)
2、初始化配置
3、使用
4、路由
- [4.1 openclaw.json 里写死了默认主模型：](#4.1 openclaw.json 里写死了默认主模型：)
- [4.2 会话里也持久化了同样选择（agents/main/sessions/sessions.json）：](#4.2 会话里也持久化了同样选择（agents/main/sessions/sessions.json）：)
- [4.3 模型引用的解析规则](#4.3 模型引用的解析规则)
- [4.4 OpenRouter 插件如何接入](#4.4 OpenRouter 插件如何接入)
- [4.5 鉴权（API Key）解析顺序](#4.5 鉴权（API Key）解析顺序)
- [4.6 Gateway 的角色](#4.6 Gateway 的角色)
- [4.7 可选模型与 failover](#4.7 可选模型与 failover)
- [4.8 ~/.openclaw 各目录/文件用途](#4.8 ~/.openclaw 各目录/文件用途)
- 4.9对应关系（简要结论）

1、安装

1.1 安装node

brew install node@23

验证安装

node -v

npm -v

1.2 安装openclaw

npm install -g openclaw@latest

验证openclaw --version

2、初始化配置

openclaw onboard

1.风险提示，

QiuickStart
配置AI模型API Key

在openRouter里注册一个api keys,然后选openAI

channel通信平台，选跳过 skip for now
选skills ,skip for now
是否开启Hooks 选 skip for now
How do you want to hatch your bot？（在哪孵化你的机器人助手？）

推荐选就行。

3、使用

窗口A: openclaw gateway 保持打开

窗口B: openclaw dashboard ->自动打开网页

4、路由

配置选模型 → 插件选 Provider → 鉴权取 Key → OpenAI 兼容 API 打到 OpenRouter

复制代码

ls  ~/.openclaw
agents
.env
devices
exec-approvals.json
flows
gateway-supervisor-restart-handoff.json
identity
logs
memory
npm
openclaw.json
openclaw.json.last-good
plugin-skills
plugins
service-env
tasks
tmp
tui
update-check.json
workspace

4.1 openclaw.json 里写死了默认主模型：

"model": { "primary": "openrouter/free" }

含义是：

字段	值	含义
Provider	openrouter	走内置 OpenRouter 插件
Model ID	free	发给 OpenRouter 的模型名是 free（OpenRouter 的免费路由模型）

4.2 会话里也持久化了同样选择（agents/main/sessions/sessions.json）：

model: openrouter/free

modelProvider: openrouter

authProfileOverride: openrouter:default（自动选的鉴权配置）

所以你现在每次对话，实际 HTTP 请求会打到 OpenRouter，模型参数是 free；具体落到哪家底层模型，由 OpenRouter 平台决定

4.3 模型引用的解析规则

OpenClaw 用 provider/model 格式（见 parseModelRef）：

openrouter/free → provider=openrouter, model=free

openrouter/auto → OpenRouter 自动选模型

openrouter/openai/gpt-4o → provider 仍是 openrouter，model 是 openai/gpt-4o（OpenRouter 上的完整模型 ID）

无 / 的裸名会套默认 provider（默认是 openai

agents.defaults.models 是允许列表 + 别名，例如：

openrouter/auto 别名 OpenRouter

openai/gpt-5.5 别名 GPT

切换模型可用 /model 命令或改 primary，但必须在 allowlist 里。

4.4 OpenRouter 插件如何接入

plugins.entries.openrouter.enabled: true 会加载扩展，核心行为：

Base URL: https://openrouter.ai/api/v1

API 形态: openai-completions（OpenAI Chat Completions 兼容）

环境变量: OPENROUTER_API_KEY

动态模型：插件可按 modelId 查能力表；未在本地 catalog 的也会动态构造请求

agents/main/agent/models.json 里缓存了 provider 定义，其中 openrouter 段：

"baseUrl": "https://openrouter.ai/api/v1",

"api": "openai-completions",

"apiKey": "OPENROUTER_API_KEY"

表示运行时从环境变量名 OPENROUTER_API_KEY 取密钥，而不是写死在 models.json 里。

4.5 鉴权（API Key）解析顺序

配置了三处（会合并使用）：

~/.openclaw/.env

OPENROUTER_API_KEY=sk-or-v1-...

openclaw.json → auth.profiles

openrouter:default → provider: openrouter, mode: api_key

运行时 store agents/main/agent/auth-profiles.json

实际保存了 openrouter:default 的 key（onboard / Cursor 配置后写入）

auth-state.json 显示当前 lastGood 是 openrouter:default，Google 曾因 rate_limit 进入 cooldown，所以系统稳定走 OpenRouter。

鉴权解析逻辑（model-auth）大致是：

auth profile (openrouter:default)

→ auth-profiles.json 里的 key

→ 或 .env 的 OPENROUTER_API_KEY

→ 或 models.json 的 OPENROUTER_API_KEY 标记

4.6 Gateway 的角色

"gateway": {

"mode": "local",

"port": 18789,

"bind": "loopback"

}

本机 127.0.0.1:18789 上跑 Gateway

客户端（TUI、Control UI、配对设备）连 Gateway，不直接连 OpenRouter

Gateway 把消息交给 agents/main，再由 Agent 运行时发 LLM 请求

这是本地网关 + 远程 LLM API 的模式，

4.7 可选模型与 failover

agents.defaults.model 还可配置 fallbacks（你当前未配）。

auth-state.json 的 usageStats / cooldownUntil 用于 provider 失败时切换 profile（例如 Google 限流后偏向 OpenRouter）。

OpenRouter 侧还支持 provider 路由参数（provider-routing），可在 models.providers.openrouter.params 或单模型 params 里配 OpenRouter 的 provider 偏好。

4.8 ~/.openclaw 各目录/文件用途

openclaw.json

路径	用途
主配置：	默认模型、Gateway、插件开关、auth profile 声明、tools、session 策略
openclaw.json.bak ~ .bak.4	每次改配置自动备份的历史版本
openclaw.json.last-good	上次校验通过的配置快照，用于回滚
.env	环境变量（如 OPENROUTER_API_KEY），Gateway/CLI 启动时加载
agents/	各 Agent 运行时数据；你主要是 main
agents/main/agent/auth-profiles.json	各 provider 的 API Key 明文存储（运行时 auth store）
agents/main/agent/auth-state.json	哪个 profile 最近可用、限流 cooldown、使用统计
agents/main/agent/models.json	Provider 目录缓存（baseUrl、模型列表、apiKey 引用方式）
agents/main/sessions/	会话元数据、对话 jsonl、当前选用的 model/auth
agents/main/agent/codex-home/	Codex 插件相关会话与临时插件（若启用 codex）
workspace/	Agent 工作区（AGENTS.md、SOUL.md 等注入系统提示的文件）
gateway-supervisor-restart-handoff.json	Gateway 进程重启时的 handoff 标记（launchd 监督用）
service-env/	macOS launchd 服务的环境脚本（ai.openclaw.gateway.env）
identity/device.json	本机设备 Ed25519 密钥对，用于 Gateway 设备认证
devices/paired.json	已配对客户端（如 control-ui webchat）及 token
devices/pending.json	待配对设备
exec-approvals.json	危险命令执行审批的 Unix socket / token
plugins/installs.json	已安装插件注册表（体积较大）
plugin-skills/	插件自带的 Skill（如 browser-automation）
npm/	Skill/插件依赖的本地 npm 安装目录（含 codex 等）
logs/	config-health.json、config-audit.jsonl 等运行日志
tmp/	临时日志、Gateway 锁文件
tui/	终端 UI 上次会话状态
memory/	Agent 长期记忆存储（目前为空）
flows/	工作流定义（空）
tasks/	TaskFlow 任务持久化（空）
update-check.json	上次检查更新的时间

4.9对应关系（简要结论）

客户端: TUI / Web Control UI
Gateway 本地 :18789
Agent main
解析 model: openrouter/free
OpenRouter 插件
鉴权 openrouter:default
HTTPS openrouter.ai/api/v1
OpenRouter 选后端模型

openclaw onboard 写了 Gateway、workspace、插件开关、auth profile 骨架。

cursor改路由实质是：把 primary 设为 openrouter/free，启用 openrouter 插件，写入 OPENROUTER_API_KEY 到 .env 和 auth-profiles.json。

实际 LLM 调用：OpenClaw Agent → OpenRouter 插件 → https://openrouter.ai/api/v1 + Authorization: Bearer <你的 key> + model: "free"。

多模型能力来自 OpenRouter 平台上的模型 ID（free、auto、openai/gpt-4o 等）。