ARTICLE DETAIL

资讯详情

深耕郑州网站建设与运营推广的一线实战洞察。

vscode 使用 claude code 的一点记录:从 settings 到 github 的完整配置

vscode 使用 claude code 的一点记录:从 settings 到 github 的完整配置 1. 从 Loading sessions 卡死说起vscode claude code 插件配置到底难在哪如果你在 VS Code 里装完 Claude Code 插件打开面板却一直停在 “Loading sessions...”大概率不是你的 settings 写错了而是插件版本和本地配置之间有一层没对齐。我这次踩的坑就是插件装的是 2.1.122settings.json 里 endpoint 指向了自建通道结果面板死活加载不出来换到 2.1.123 之后立刻正常。所以这篇记录不打算只讲“怎么装”而是把 vscode claude code 插件从 settings 参数、endpoint 改写、GitHub 协作到常见报错排查串成一条能直接跟做的路径。先说清楚这个插件能做什么。Claude Code 在 VS Code 里不是简单的聊天窗口它更像一个能读写工作区文件、执行终端命令、按任务拆步骤的编码代理。你可以在侧边栏让它读某个目录、改某个函数、跑测试甚至让它根据 issue 描述生成补丁。适合谁适合已经在用 VS Code 写代码、想让模型直接参与文件级操作的人也适合团队里想把模型请求统一到一个可控 endpoint、方便做密钥和用量管理的人。核心检索词先摆出来vscode claude code 插件配置、settings.json 参数、endpoint 改写、GitHub 协作、Loading sessions 排查。这几个词基本覆盖了从安装到跑通的全部环节。下面按“问题场景 → 前置准备 → 可复制配置 → 验证请求 → 报错排查 → 后续协作”的顺序展开每一步都给到能直接粘贴的片段和验证命令。需要提前说明一点插件本身负责的是 VS Code 内的交互层真正发请求的是它背后的 CLI 或扩展进程。所以当面板卡在 Loading sessions 时问题可能出在三个地方插件版本、settings 里的 endpoint/密钥、以及本地网络到 endpoint 的可达性。把这三层分开查比反复改 settings 有效得多。2. 把 endpoint 统一到 TaoToken前置准备与密钥获取在改 settings 之前先把请求通道确定下来。我这次的做法是把 endpoint 统一到 TaoToken 的 API 地址这样插件、CLI、以及后面 GitHub 协作里用到的模型调用都走同一个入口密钥和用量也好统一看。TaoToken 的 API 地址是 https://taotoken.net/api 官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。注意 API 地址后面不加 UTM 参数直接用它作为 Base URL 即可。第一步是拿 Key。打开 https://taotoken.net/api-keys 登录后创建一个新的 API Key。建议按用途命名比如 “vscode-claude-code”方便后面在 GitHub 协作或 CI 里区分。创建后立刻复制页面通常只显示一次。这个 Key 就是后面 settings 里的 apiKey 字段也是 Claude Code 三件套里的第二件。第二步确认模型 ID。在模型对话页面 https://taotoken.net/models 可以看到当前可用的模型标识比如 claude 系列的具体名称。这个 ID 要填到 settings 的 model 字段里不能只写 “claude” 这种模糊值否则请求会返回模型不存在的错误。三件套到这里就齐了Base URL https://taotoken.net/api API Key 你刚创建的那串Model ID 模型列表里的准确标识。第三步是环境检查。在终端里先确认能访问 endpoint可以用 curl 做一次最小请求。把下面的命令里的 $TAOTOKEN_KEY 换成你的 Key$MODEL_ID 换成模型标识curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_KEY \ -H Content-Type: application/json \ -d { model: $MODEL_ID, messages: [{role: user, content: ping}], max_tokens: 16 }如果返回里有 choices 字段和内容说明通道是通的。这一步很关键因为它把“网络可达性”和“插件配置”分开了。如果 curl 都不通那 VS Code 里再怎么改 settings 也没用。如果 curl 通了但插件还卡 Loading sessions问题就落在插件版本或 settings 格式上。另外提醒一句不要把 Key 硬编码到会提交到 GitHub 的文件里。后面讲 GitHub 协作时会用环境变量或 secrets 的方式注入。现在先在本地把 Key 放到 shell 环境里比如写进 ~/.zshrc 或 ~/.bashrc用 export TAOTOKEN_KEY...这样终端和插件都能读到。3. 可复制的 settings 片段vscode claude code 插件参数逐项说明这一节是全文最核心的可复制配置。VS Code 的 Claude Code 插件读取的是工作区或用户级的 settings.json路径通常是 ~/.config/Code/User/settings.jsonLinux、~/Library/Application Support/Code/User/settings.jsonmacOS或 %APPDATA%\Code\User\settings.jsonWindows。你也可以在项目根目录建 .vscode/settings.json只对当前工作区生效。下面给一份完整片段字段名按插件实际读取的键来写{ claude-code.enabled: true, claude-code.baseUrl: https://taotoken.net/api, claude-code.apiKey: ${env:TAOTOKEN_KEY}, claude-code.model: 你的模型ID, claude-code.maxTokens: 4096, claude-code.temperature: 0.2, claude-code.autoStart: true, claude-code.terminal.integrate: true, claude-code.workspace.allowWrite: true, claude-code.workspace.allowTerminal: true }逐项解释一下。baseUrl 指向 TaoToken 的 API 根地址注意不要带 /v1 后缀插件内部会自己拼路径如果你写成 https://taotoken.net/api/v1有些版本会拼成 /v1/v1/chat/completions 导致 404。apiKey 用 ${env:TAOTOKEN_KEY} 引用环境变量这样文件可以安全提交到 GitHub不会泄露密钥。model 填模型列表里的准确 ID。maxTokens 和 temperature 按需调编码任务建议 temperature 低一点减少胡改。autoStart 控制打开 VS Code 时是否自动拉起插件进程。terminal.integrate 让插件能复用集成终端执行命令。allowWrite 和 allowTerminal 是权限开关第一次跑通时建议都开确认没问题后再按项目收紧。如果你在团队里想统一配置可以把这份 settings 放到 .vscode/settings.json 并提交但 apiKey 那行必须保持 ${env:...} 形式让每个人在本地注入自己的 Key。还有一个容易忽略的点插件版本。我这次卡 Loading sessions 的直接原因就是 2.1.122 这个版本对自定义 baseUrl 的处理有 bug升级到 2.1.123 后同一份 settings 直接生效。所以配置写完后先去扩展面板确认版本必要时手动下载最新 vsix 安装。插件市场地址是 marketplace.visualstudio.com搜索 “Claude Code” 即可。安装新版本前先卸载旧版本避免两个版本共存导致进程冲突。如果你用的是 Claude Code CLI 而不是纯插件配置会落在 ~/.claude/settings.json 或项目级 .claude/settings.json字段名类似但层级不同。CLI 场景下同样把 baseUrl 指向 https://taotoken.net/api Key 用环境变量注入。两种方式不要混用同一份文件否则会出现“插件读到了 CLI 的配置但字段不匹配”的怪问题。4. 验证请求是否生效从面板加载到实际对话配置写完后不要直接开面板就以为好了按下面步骤验证能快速定位问题在哪一层。第一步重启 VS Code让 settings 重新加载。第二步打开命令面板CtrlShiftP 或 CmdShiftP运行 “Claude Code: Open” 或类似命令观察面板是否还停在 Loading sessions。如果这次能正常显示会话列表或输入框说明插件版本和 settings 格式都对上了。第三步发一条最小请求。在面板里输入 “读取当前目录下的 package.json 并告诉我 name 字段”看它是否能调用工具读文件并返回结果。这一步验证的是插件到 endpoint 的完整链路。如果返回内容正常说明 Base URL、Key、Model ID 三件套都生效了。第四步在集成终端里跑一次 CLI 验证确认同一套凭证在命令行也通export TAOTOKEN_KEY你的Key curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_KEY \ -H Content-Type: application/json \ -d {model:你的模型ID,messages:[{role:user,content:say ok}],max_tokens:8}如果终端返回正常但面板仍卡住问题基本锁定在插件版本或 VS Code 的扩展宿主进程。可以尝试卸载插件 → 重启 VS Code → 重新安装最新版 → 再打开面板。我实测下来这一步解决了 2.1.122 的 Loading sessions 问题。第五步检查输出日志。VS Code 的 “输出” 面板里选择 “Claude Code” 通道能看到插件发的请求和返回。如果看到 401说明 Key 没读到或失效如果看到连接被拒说明 baseUrl 写错或本地网络到 endpoint 不通如果看到 “reading choices” 相关报错通常是返回体不是预期 JSON可能是 baseUrl 多了 /v1 或少了路径。把这些日志和 curl 结果对照能省很多瞎猜时间。验证通过后建议把这次成功的 settings 片段和插件版本号记在项目 README 或内部文档里。下次换机器或新人加入直接照抄不用再经历一遍 Loading sessions 的折腾。5. 常见报错排查401、local proxy failed、reading choices、OAuth这一节按真实报错来对照每条都给触发原因和修法。先列一个速查表再展开说明。报错关键词常见原因修法401 UnauthorizedKey 未注入或失效检查 ${env:TAOTOKEN_KEY} 是否在 VS Code 启动环境里可见local proxy failed本地代理进程未启动或端口冲突关闭冲突进程或改用直连 baseUrlreading choices返回体不是预期 JSON检查 baseUrl 是否多了 /v1或模型 ID 不存在OAuth / login required插件走了默认登录流程在 settings 里显式指定 baseUrl 和 apiKey跳过 OAuthLoading sessions 卡死插件版本 bug升级到最新版卸载旧版后重装401 是最常见的。VS Code 从图形界面启动时不一定继承你 shell 里的环境变量。如果你在 ~/.zshrc 里 export 了 TAOTOKEN_KEY但 VS Code 是从 Dock 或开始菜单启动的它可能读不到。解决办法有两个一是从终端用code .启动 VS Code这样会继承当前 shell 环境二是在 settings 里临时写明文 Key 做验证确认通了再换回环境变量。注意明文 Key 不要提交到 GitHub。local proxy failed 通常出现在你本地跑了某个转发进程但插件配置的端口和它不一致。如果你没有主动跑本地转发直接把 baseUrl 指向 https://taotoken.net/api 即可不需要经过本地端口。如果确实需要本地转发确认进程在跑、端口没被占用并且 settings 里的 baseUrl 指向 http://127.0.0.1:对应端口。reading choices 这个报错说明插件拿到了返回但解析 choices 字段失败。最常见的原因是 baseUrl 写成了 https://taotoken.net/api/v1插件又拼了一次 /v1请求打到了不存在的路径返回的是 HTML 或错误 JSON。把 baseUrl 改回 https://taotoken.net/api 即可。另一个原因是 model 字段填了不存在的 ID返回体里没有 choices。去模型列表页核对准确 ID。OAuth 相关报错说明插件在尝试走默认的登录授权流程而不是用你配置的 Key。这通常发生在 settings 里没有显式设置 baseUrl 和 apiKey或者字段名写错导致插件没读到。确认键名和插件版本匹配必要时查插件文档的配置章节。显式配置后插件会跳过 OAuth 直接用 Key。最后是 Loading sessions 卡死。这个我踩得最久。表现是面板一直转圈输出日志里可能没有任何请求记录说明插件在初始化阶段就卡住了。原因大概率是插件版本对自定义 endpoint 的支持有缺陷。处理方式去扩展面板看当前版本去 marketplace 看最新版本下载最新 vsix卸载旧版安装新版重启 VS Code。我这次从 2.1.122 换到 2.1.123 后同一份 settings 直接正常。排查时建议按“先 curl 再插件、先版本再配置、先日志再猜测”的顺序。curl 通了再动插件版本对了再调参数日志有了再定位。这样每一步都有依据不会来回改配置改到怀疑人生。6. GitHub 协作与后续把配置带进仓库而不泄露密钥跑通本地之后下一步通常是把这套配置带进 GitHub 协作流程。核心原则是配置文件可以提交密钥不能提交。把 .vscode/settings.json 里的 apiKey 写成 ${env:TAOTOKEN_KEY}然后把这个文件提交到仓库。团队成员克隆后各自在本地注入自己的 Key就能用同一份配置连到 TaoToken 的统一通道。在 GitHub Actions 或 CI 里把 Key 放到 repository secrets 里比如命名为 TAOTOKEN_KEY然后在 workflow 里通过 env 注入。这样 CI 里的模型调用也走同一个 endpoint用量和权限统一管理。如果你在本地用 Claude Code 做 issue 到补丁的流程可以让它读 issue 描述、改文件、跑测试再把 diff 提交到分支人工 review 后合并。插件负责交互GitHub 负责版本和协作两者通过工作区文件衔接。需要长期跑编码任务或 Agent 流程的话可以了解 Coding Plan 相关入口 https://taotoken.net/coding-plan 把模型调用额度按计划管理。日常验证模型是否可用用模型对话页面 https://taotoken.net/models 快速试。接入文档在 https://taotoken.net/doc 里面有各语言和工具的接入示例遇到字段不确定时先查文档再改配置。最后给一个实用技巧把这次跑通的 settings 片段、插件版本号、以及 curl 验证命令写进项目的 docs/setup.md新人照着做能少走弯路。密钥注入方式也写清楚避免有人图省事把 Key 写进文件提交。配置这件事一次写对后面就是复制粘贴。
返回列表