灿海星图指南：Claude Code 5步接入与3个沉默陷阱

凌晨两点，我对着终端敲了第 14 遍 /status，返回的还是 401 Unauthorized。API Key 复制粘贴了三遍，网络也没问题，但 Claude Code 就是不认。翻遍了灿海星图用户群的 200+ 条求助消息后，我发现了一个规律：十个 401 里有七八个是同一个原因——BASE_URL 少了个 /anthropic 结尾。Claude Code 不会告诉你 "URL 格式错误"，它只会静默地把 401 丢给你，让你怀疑是不是 Key 过期了、网络被墙了、或者自己手抖打错了。

本文数据来源于互联网公开信息及灿海星图用户群实际交流记录，仅供技术参考，具体配置以灿海星图官方文档为准。文中提到的 API 端点和价格信息可能随服务更新而变化。

核心操作：5步接入

第 1 步：安装 Claude Code

Windows 走 winget，macOS 走 brew，Linux 走 npm：

# Windows
winget install Anthropic.ClaudeCode

# macOS
brew install --cask claude-code

# Linux / 通用
npm install -g @anthropic-ai/claude-code

装完后 claude --version 验证一下。如果提示 command not found，关掉终端重开——Windows 下 npm 全局目录不一定在 PATH 里，重启终端是最快的修复方式。

Node.js 版本要求 ≥ 18。低于这个版本会报 SyntaxError: Unexpected token '?'，因为 Claude Code 用了可选链等 ES2020 语法。

截图 1：终端中执行 claude --version 的截图，显示版本号 "Claude Code v2.x.x" 和 Node.js 版本 "v20.x.x"。如果这里报错，先检查 Node 版本，不要跳过。

第 2 步：获取灿海星图 API 配置

登录灿海星图控制台，在 "API 管理" 页面复制三样东西：

注意 BASE_URL 必须以 /anthropic 结尾。Claude Code 会在你给的 URL 后面自动拼接 /v1/messages，所以完整请求路径是 https://www.lumaocean.com/anthropic/v1/messages。如果只写到 lumaocean.com，请求会打到 lumaocean.com/v1/messages——这是一个不存在的端点，Claude Code 返回 401。

第 3 步：配置三层 settings.json

Claude Code 支持三层级联配置。理解这个三级结构，后面的踩坑会少一半：

高优先级覆盖低优先级。 三个文件路径都不能写错——写成 ~/.claude.json 不会生效，Claude Code 不会告诉你文件没找到。

全局 ~/.claude/settings.json 的推荐起步配置：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://www.lumaocean.com/anthropic",
    "ANTHROPIC_API_KEY": "sk-your-key-here"
  }
}

项目级 .claude/settings.json 里放模型选择和权限策略：

{
  "model": "claude-sonnet-4-20250514",
  "permissionMode": "acceptEdits",
  "allowedTools": [
    "Bash(git diff:*)",
    "Bash(git log:*)",
    "Bash(git status:*)",
    "Bash(npm:*)",
    "Bash(node:*)",
    "Read",
    "Write",
    "Edit",
    "Glob",
    "Grep"
  ]
}

permissionMode 的三档选择：

• default：每个命令都弹确认窗，安全但打断节奏
• acceptEdits：只对文件编辑自动放行，系统命令仍需确认（推荐日常使用）
• bypassPermissions：全部自动执行，只在沙箱里用这个

settings.local.json 放个人的 API Key，记得加入 .gitignore：

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-your-personal-key-here"
  }
}

截图 2：VS Code 中同时打开三个 settings.json 文件的截图，左侧文件树显示 ~/.claude/settings.json、.claude/settings.json、.claude/settings.local.json 的层级关系。右侧编辑器里用注释标注每层的职责——全局放 URL、项目放模型和权限、local 放 Key。

第 4 步：写入 CLAUDE.md

所有配置里回报率最高的不是 MCP 也不是 Hook——是 CLAUDE.md。

在项目根目录放一个 CLAUDE.md，Claude Code 每次启动都会加载它作为系统指令。我现在的模板：

# 项目：xxx

## 技术栈
- 前端：React 18 + TypeScript + Tailwind CSS
- 后端：Node.js + Express
- 测试：Vitest
- 包管理：pnpm

## 命名规范
- 组件：PascalCase（UserProfile.tsx）
- 工具函数：camelCase（formatDate.ts）
- 常量：UPPER_SNAKE_CASE

## 测试命令
- 单文件：npx vitest run path/to/file.test.ts
- 全量：npx vitest run
- 监听模式：npx vitest

## 禁止使用的库
- moment.js（用 date-fns 替代）
- axios（用 fetch 替代）

## 工作流
1. 改代码前先跑现有测试确保通过
2. 改完跑相关测试
3. 不要自动 git commit

刚开始我只写了两行，后来慢慢往上加——项目结构、命名规范、测试命令、禁止的库。写清楚之后 Claude Code 的犯错率明显下降。现在进新项目第一件事就是写 CLAUDE.md。

第 5 步：验证配置

启动后输入 /status，预期输出：

如果显示的是 https://api.anthropic.com（官方端点）而不是灿海星图的 URL，说明你的 settings.json 没生效。排查顺序：

1. python -m json.tool ~/.claude/settings.json 验证 JSON 合法性（尾逗号、注释都不允许）
2. 确认文件路径是 ~/.claude/settings.json，不是 ~/.claude.json
3. 彻底关闭终端重开——配置在启动时读取，不会热加载
4. 运行 claude doctor 看诊断输出

踩坑实录：3个沉默陷阱

这三个坑的共同特点是：Claude Code 不会报错，只是静默地用错误配置跑。

踩坑 1：BASE_URL 差一个后缀，报 401 不报 URL 错误

现象：settings.json 写好了，API Key 确认三遍了，/status 就是 401。

原因：Claude Code 的请求路径是 ${BASE_URL}/v1/messages。灿海星图要求 BASE_URL 以 /anthropic 结尾，lumaocean.com/v1/messages 和 lumaocean.com/anthropic/v1/messages 是两个不同的端点。前者不存在，Claude Code 拿到的 HTTP 状态码是 401（也可以是 404，取决于代理层实现），但 Claude Code 统一把非 200 的响应处理为 401，不会告诉你实际返回了什么状态码。

解决：echo $env:ANTHROPIC_BASE_URL 确认值以 /anthropic 结尾。根据灿海星图用户群的交流记录，2025 年 10 月至 2026 年 5 月期间，BASE_URL 相关问题是群内求助频次最高的单一问题，占比约 70%¹。我自己第一次配也在这里卡了 40 分钟。

踩坑 2：Windows 环境变量改了，Claude Code 读到的是旧值

现象：在 "系统属性 → 环境变量" 里设了 ANTHROPIC_API_KEY，echo $env:ANTHROPIC_API_KEY 也能打出来，但 Claude Code 就是读不到。或者更诡异的——读到的是一个你删掉了的旧 Key。

原因：Windows 修改系统环境变量后做了两件事：(1) 把新值写入注册表，(2) 广播 WM_SETTINGCHANGE 消息通知正在运行的进程刷新。问题在于——不是所有进程都会响应这条消息。PowerShell 窗口、VS Code 内置终端、Windows Terminal 的标签页，很多情况下保留了旧的环境变量快照。echo 显示新值是因为你当前 Shell 收到了广播，但 Claude Code 启动时可能从父进程继承了旧快照。

解决：不要在已有终端里改了环境变量就重开 Claude Code。正确做法：(1) 改完系统环境变量，(2) 关闭所有终端和 VS Code，(3) 从开始菜单重新打开 PowerShell，(4) echo $env:ANTHROPIC_API_KEY 确认，(5) 启动 Claude Code。如果还不行，重启电脑——Windows 下最快的方式有时候就是重启。

踩坑 3：MCP 服务器配置正确，工具列表始终为空

现象：.claude/mcp.json 配好了，/mcp 能看到服务器名，但名字是灰色的，/tools 里没有对应工具。

原因：MCP 服务器的启动命令（command 字段）依赖运行时的环境——当前工作目录、PATH、node_modules 位置。Claude Code 从你的 home 目录启动 MCP 子进程，而不是项目根目录。如果你的 MCP server 是 node ./mcp-server/index.js 这种相对路径，Claude Code 在 ~ 下找不到这个文件，连接静默失败。没有错误提示，没有告警日志，/mcp 列表里只显示一个灰色名称。

解决：MCP 配置里所有路径用绝对路径，或者用 npx：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-filesystem", "C:/Users/你的用户名/projects"]
    }
  }
}

排查技巧：启动 Claude Code 后输入 /mcp，看服务器名颜色——白色 = 已连接，灰色 = 连接失败。如果灰色，去 ~/.claude/logs/ 找对应的日志文件，搜索 mcp 看具体报什么错。

常见疑问

Q1：三个 settings.json 都配了同一个字段，谁说了算？

优先级：settings.local.json > .claude/settings.json > ~/.claude/settings.json。

是字段级别的覆盖，不是整个文件替换。比如全局配了 baseURL 和 model，项目级只配了 model——结果会用全局的 baseURL 和项目级的 model。不需要把全局的配置全复制到项目级文件里。

settings.local.json 不接入 Git 跟踪，适合放 API Key 和个人偏好。文件路径必须是 .claude/settings.local.json，写成 ~/.claude/settings.local.json 不会生效。

Q2：接入第三方 API 后，权限弹窗和沙箱功能还正常吗？

权限弹窗是 Claude Code 客户端本地机制，和用哪个 API 无关——照常工作。

沙箱隔离（dangerouslyDisableSandbox 相关功能）需要额外配置。第三方 API 不会自动继承 Anthropic 官方沙箱策略，如果你的工作场景对安全性要求高，建议在项目级 settings.json 里配置 permissionMode 和 allowedTools 白名单来替代沙箱的部分能力。

Q3：配了多个模型角色但 token 消耗完全一样，是不是根本没切换？

大概率是第三方 API 端只部署了一个模型。Claude Code 客户端不知道后端有几个模型，你切 /model 它以为自己切换成功了，但所有请求打到同一个端点，后端一律路由到唯一的模型。

验证方法：claude --debug 启动后做一次对话，在日志里找 "model" 字段，看实际发送的模型名是什么。如果 /model 切换了但日志里 model 字段始终不变，说明后端只有一个模型。

我为什么不用 Cursor / Codex / Copilot 替代它

写过这篇之前，我的电脑上跑过 Cursor、GitHub Copilot、Codex CLI 三个工具。最后日常编码主力还是 Claude Code + 灿海星图。每个工具都有它擅长的场景，选什么取决于你主要干什么。

Cursor 的 Tab 补全确实快，改一个变量名整个文件跟着变，处理熟手工作中的机械操作非常顺手。但它的 Agent 模式跑大型重构时，改到一半经常丢上下文——改着改着忘了自己要干什么。我试过让它把一个 Express 路由拆成 Controller + Service 层，改了 4 个文件后第 5 个文件开始自由发挥，加了一些不存在的方法调用。Claude Code 在长任务上更稳，因为它会把 CLAUDE.md 作为系统指令固定加载，上下文不会在中间丢失。

GitHub Copilot 胜在 IDE 集成——VS Code 里开箱即用，不用任何配置。但它只有 Chat 和 Inline 补全，没有 Agent 模式。不能让它跑终端命令、不能让它改多个文件后自己跑测试、不能让它 git diff 后自己判断改了什么。Copilot 的角色更像是 "副驾驶建议"，Claude Code 的角色是 "你能直接把方向盘给它，但眼睛得盯着路"。

OpenAI Codex CLI（开源的那个，不是 GitHub Copilot 的底层模型）刚出来的时候我试了一周。它的 codex exec 概念挺好——给个自然语言指令直接执行。但当时（2025 年 12 月左右）对大型代码库的索引速度比 Claude Code 慢不少，一个 5 万行 TypeScript 项目，Codex 索引要 40 秒，Claude Code 只要十几秒。这个问题应该会随着版本迭代改善，但目前还不是一个量级。

所以你适合用哪个：

当前选择：日常开发主力 Claude Code，快速补全切回 Cursor，Code review 用 GitHub Copilot Chat。三开不冲突，但一个月下来 Claude Code 占了 70% 的 API 调用量——不是因为它最好，是因为我的工作里有大量"改完代码 → 跑测试 → 看结果 → 再改"的循环，这个循环交给 Claude Code 自己跑完，比我手动来回切快得多。