hasCompletedOnboarding详解

一、先搞懂：这是啥配置？为啥会有这个文件？

你截图里的 C:\Users\iwenw\.claude.json，是 Claude Code 的「首次引导完成标记文件」，作用是绕过它的地区校验 / 首次使用引导流程。

 

---

 

1. 这个配置是干嘛的？ 

文件里的 "hasCompletedOnboarding": true 是一个布尔开关，含义是：

告诉 Claude Code：「我已经完成了首次引导流程，不需要再做地区校验、账号登录等初始化步骤了」

为什么会有这个配置？

1. Claude Code 原生有地区限制：Anthropic 官方服务在中国大陆无法直接使用，首次启动时会触发位置校验、账号登录、服务可用性检查，直接报错无法进入。
2. 这个开关是 “绕过初始化流程” 的关键：只要设置为 true，Claude Code 会直接跳过所有首次引导和地区校验，直接进入命令行交互模式，让你后续可以接入 DeepSeek / 通义千问等第三方模型。
3. 注意：它本身不解决模型使用问题，只是让你能正常启动 Claude Code 命令行，后续模型还是要通过 settings.json 配置第三方模型。

2. 它和你之前用的 ~/.claude/settings.json 是什么关系？

表格

 

文件	作用	优先级
.claude.json	控制首次引导、地区校验是否跳过，只影响启动流程	启动时最先加载
~/.claude/settings.json	配置模型、API 地址、环境变量、文件黑白名单	启动后加载，控制模型调用

 

简单说：.claude.json 是「让软件能打开」，settings.json 是「让软件能用第三方模型干活」。

 

二、Mac 上怎么设置这个配置？

Mac 上对应的文件路径和操作和 Windows 不一样，下面给你完整可直接执行的步骤：

 

1. Mac 上的文件路径

Mac 上 Claude Code 的首次引导标记文件，默认路径是：

 

~/.claude.json

 

也就是当前用户的根目录下，直接创建 .claude.json 文件即可。

2. 配置步骤（终端命令，一步到位） 

# 1. 直接创建并写入配置（自动创建文件）
echo '{ "hasCompletedOnboarding": true }' > ~/.claude.json

# 2. 查看文件是否创建成功
cat ~/.claude.json

输出内容应该是：

{ "hasCompletedOnboarding": true }

3. 验证配置是否生效

1. 关闭所有终端窗口，重新打开；
2. 进入你的项目目录，直接输入 claude；
3. 能正常进入 > 交互模式，没有地区校验 / 引导报错，说明配置成功。

---

 

三、补充说明 & 常见坑

1. 这个配置只是启动用的，不能解决模型调用问题：
    
   它只是让 Claude Code 能打开，要真正使用 DeepSeek / 千问，还是要配置 ~/.claude/settings.json 的第三方模型地址和 API Key，否则输入指令会报 401/402 错误。
2. 如果已经配置过 settings.json，还要不要设置这个？
    
   建议设置。因为即使你配置了第三方模型，Claude Code 启动时依然会做首次引导校验，不设置这个开关可能会卡在引导流程里，无法进入命令行。
3. Mac 上文件找不到怎么办？
   • 终端执行 cd ~ && ls -la 看是否有 .claude.json；
   • 没有的话，用上面的 echo 命令创建即可，文件是 Claude Code 识别的，不是自动生成的。 

四、Mac 完整启动流程（结合这个配置）

 

# 1. 创建 .claude.json 绕过引导校验
echo '{ "hasCompletedOnboarding": true }' > ~/.claude.json

# 2. 编辑全局 settings.json 配置 DeepSeek 模型
code ~/.claude/settings.json

# 3. 进入项目目录，启动 claude
cd 你的项目目录
claude

 

这样就能实现：跳过引导校验 → 正常启动 → 用 DeepSeek / 千问模型干活。