[个人笔记] WSL 完整使用指南及 Claude Code 配置记录：TaoToken 统一 Key 接入 settings.json 骨架

1. 为什么我还在 WSL 里跑 Claude CodeWSL 是 Windows 上的一套 Linux 子系统能在不装双系统、不折腾虚拟机的前提下直接跑 Ubuntu 命令行环境。Claude Code 是 Anthropic 推出的终端 AI 编码助手能在项目目录里读文件、改代码、跑命令。把这两样凑一起适合谁适合主力机是 Windows、但项目依赖 Linux 工具链gcc、make、python3、node的开发者也适合想用统一 Key 管理多个 AI 编码工具、不想每个工具单独配一遍的人。我自己的场景是Windows 上写前端和脚本但有些构建脚本必须在 Linux 下跑于是长期用 WSL2 Ubuntu。Claude Code 早期版本在 Windows 原生下体验一般我就把它装在 WSL 里。后来发现真正麻烦的不是装而是配置——尤其是把 API 通道统一到一个 Key 上让 Claude Code、其他 CLI 工具共用一套凭证。这篇笔记就把 WSL 安装、Node 环境、settings.json 骨架、TaoToken 统一 Key 接入、验证与排障整条链路写清楚你照着做能一次跑通。需要先说明一点Claude Code 新版本已经支持直接在 Windows 上安装不一定非要 WSL。但 WSL 环境本身对 Linux 工具链友好而且本文的 settings.json 配置思路在两种环境下通用所以这份记录仍然有参考价值。2. TaoToken 前置准备统一 Key 与 API 通道在写 settings.json 之前先把「钥匙」准备好。TaoToken 的作用是提供一个统一的 API 通道和 Key让 Claude Code 这类工具通过一个入口访问模型不用在每个工具里分别填不同的凭证。官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基础地址是 https://taotoken.net/api 。操作顺序是这样的先注册并登录进入控制台创建 API Key然后把这个 Key 记下来。控制台地址在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 创建 Key 的页面在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。如果你只是想先验证模型能不能通可以用模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 发一条消息试试。这里有个关键点Claude Code 走的是 Anthropic 风格的接口所以配置里要区分「基础地址」和「认证方式」。TaoToken 的 API 地址是 https://taotoken.net/api 在 settings.json 里通常作为 base URL 使用。Key 的格式一般以固定前缀开头复制时注意别带空格。如果你后面要长期跑编码任务或 Agent可以了解 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 接入细节查文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。注意Key 属于敏感凭证不要提交到 Git 仓库也不要贴在公开的 issue 里。建议放在用户级配置文件或环境变量中。3. WSL 与 Node 环境准备3.1 安装 WSL 并设为 WSL2以管理员身份打开 PowerShell执行自动安装wsl --install装完后设置默认版本为 WSL2wsl --set-default-version 2查看可用的发行版并安装 Ubuntuwsl --list --online wsl --install -d Ubuntu-24.04安装完成后会提示创建 Linux 用户名和密码。之后用wsl -l -v确认状态是 Running、版本是 2。3.2 更新系统并安装 Node 20进入 WSL 终端Windows Terminal 里输入wsl即可先更新包列表sudo apt update sudo apt upgrade -yNode 版本建议用 20.x通过 NodeSource 源安装比 apt 自带的版本新curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs验证node --version npm --version如果node --version输出 v20 开头说明环境就绪。这里踩过的坑是apt 自带的 nodejs 版本可能偏低Claude Code 对 Node 版本有要求所以优先用 NodeSource。3.3 安装 Claude Codenpm install -g anthropic-ai/claude-code如果遇到权限报错可以配置 npm 全局目录到用户空间npm config set prefix ~/.npm-global echo export PATH~/.npm-global/bin:$PATH ~/.bashrc source ~/.bashrc npm install -g anthropic-ai/claude-code装完后claude --version能输出版本号即可。4. settings.json 配置骨架与 TaoToken 接入Claude Code 的配置分两层用户级配置在~/.claude/settings.json项目级配置在项目根目录的.claude/settings.json。统一 Key 接入建议放在用户级这样所有项目共用一套凭证。先创建目录mkdir -p ~/.claude然后写入 settings.json。下面是一个可复制的骨架把YOUR_TAOTOKEN_API_KEY替换成你在控制台创建的真实 Key{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: YOUR_TAOTOKEN_API_KEY, ANTHROPIC_MODEL: claude-sonnet-4-20250514 }, permissions: { allow: [], deny: [] } }几个字段的含义对照如下字段作用取值示例ANTHROPIC_BASE_URLAPI 基础地址https://taotoken.net/apiANTHROPIC_AUTH_TOKEN认证令牌控制台创建的 KeyANTHROPIC_MODEL默认模型按文档填写可用模型名permissions.allow允许免确认的操作如Bash(npm run test)permissions.deny禁止的操作如Read(./.env)如果你不想把 Key 明文写进文件可以用环境变量方式。在~/.bashrc末尾追加export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENYOUR_TAOTOKEN_API_KEY然后source ~/.bashrc。settings.json 里的 env 优先级高于系统环境变量两种方式选一种即可别同时配导致冲突。提示模型名要以 TaoToken 文档里列出的可用模型为准写错会导致请求返回模型不存在。文档地址 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。5. 验证配置生效与成功结果配置写完后进入一个项目目录启动 Claude Codecd ~/projects/demo claude启动后先看它有没有报认证错误。如果配置正确会进入交互界面。在对话框里输入一句简单指令比如「列出当前目录的文件」观察是否正常返回。更直接的验证方式是用claude的非交互模式跑一条命令claude -p 用一句话说明当前目录有几个文件如果返回了合理回答说明 Key、base URL、模型三项都通了。成功结果的特征是没有 401/403 认证错误没有连接超时模型能正常输出内容。再验证一下配置文件是否被读取cat ~/.claude/settings.json确认 JSON 格式合法可以用python3 -m json.tool ~/.claude/settings.json校验。JSON 里多一个逗号都会导致解析失败Claude Code 会静默忽略配置表现就是「明明配了却还是报未认证」。6. 本篇常见错排查6.1 401 未认证最常见的原因是 Key 复制时带了空格或换行。重新cat一下 settings.json确认ANTHROPIC_AUTH_TOKEN的值是完整的一串。另一个原因是同时配了环境变量和 settings.json两者不一致时以 settings.json 为准检查有没有旧的环境变量残留。6.2 连接超时或 DNS 失败先在 WSL 里测试 API 地址连通性curl -I https://taotoken.net/api如果 curl 都连不上说明是 WSL 网络问题不是配置问题。可以重置网络sudo systemctl restart systemd-networkd sudo systemctl restart systemd-resolved6.3 模型不存在报错里出现 model not found说明ANTHROPIC_MODEL填的模型名不在可用列表里。去文档页核对当前支持的模型名改成正确的再重启 Claude Code。6.4 JSON 解析失败用校验命令定位python3 -m json.tool ~/.claude/settings.json它会指出第几行出错。常见是尾随逗号、中文引号、注释JSON 不支持注释。6.5 权限被拒如果 Claude Code 想执行某个命令但被拦检查permissions.deny里有没有误加规则。deny 优先级高于 allow一条 deny 会覆盖所有 allow。7. 后续接入与工具选择配置跑通后日常使用就是进项目目录敲claude。如果你要管理多个 Key 或查看用量去控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。需要新建或轮换 Key 时用 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。接入其他工具或查参数细节文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 是最准的来源。长期跑编码任务或 Agent 的话Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 比按量更省心。想快速验证某个模型表现直接用模型对话 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 发消息即可不用改本地配置。最后留一个实用习惯把~/.claude/settings.json纳入你的 dotfiles 备份但 Key 用占位符真实 Key 通过环境变量注入。这样换机器时配置能直接复用又不会泄露凭证。