1. 为什么要在本地跑 Claude Code 并接本地模型Claude Code 是 Anthropic 官方推出的终端 AI 编程助手能直接在命令行里读写文件、执行 Shell、跑测试、做多步任务。但官方版本默认走 Anthropic 云端 API对想研究内部实现、想接本地模型、想统一管理 API 通道的开发者来说有两个现实问题一是源码闭源二是模型通道被锁死。社区里出现了一个从 npm 包 source map 逆向还原出来的开源版本用 TypeScript 重写基于 Bun 运行时和 React Ink 终端渲染把 Claude Code 的架构完整暴露了出来。它保留了核心能力终端对话写代码、自动文件操作、Shell 命令执行、多 Agent 协作、MCP 集成、权限控制。对开发者来说这既是一份可读的架构教材也是一个可以魔改的本地编程助手底座。我这次的目标很明确把这个开源版本在本地跑起来跳过官方 OAuth 认证把模型通道指向本地模型或统一 API 网关并且用 TaoToken 的 Key 做统一管理。这样做的价值在于你可以在一个终端界面里同时管理多个模型来源本地小模型做轻量补全云端模型做复杂推理切换只改一个环境变量。适合谁看想在本地跑通 Claude Code 的开发者、想研究终端 Agent 架构的工程师、手里有本地模型Ollama、vLLM、LM Studio 等想接进编程助手的人、以及想用统一 Key 管理多模型通道的团队。整篇按“架构解读 → 环境准备 → 配置落地 → 验证 → 排障 → 通道管理”的顺序走每一步都给可复制的命令和参数。先说清楚一个前提这个开源版本是逆向还原不是官方发布部分原生模块用 shim 替代仅支持 macOS/LinuxWindows 建议走 WSL。它需要你提供一个兼容 Anthropic Messages API 的端点本地模型或网关只要实现这个协议就能接。2. Claude Code 开源版架构解读与本地模型接入前置准备先花几分钟把架构看懂后面配置才不会瞎改。整个项目分四层从下往上理解最顺。基础设施层管配置管理、权限控制、文件系统操作。配置主要来自环境变量和 settings 文件权限控制决定哪些工具调用需要用户确认。这一层是你接本地模型时最常打交道的因为ANTHROPIC_BASE_URL、ANTHROPIC_API_KEY这类变量都在这里被读取。服务层是核心包含 API 客户端、MCP 服务器、会话管理、分析遥测。API 客户端基于anthropic-ai/sdk负责把请求发到ANTHROPIC_BASE_URL指向的端点。MCP 部分实现了 Model Context Protocol 的客户端和服务端支持 OAuth 认证这是你扩展工具能力的关键。会话管理负责历史记录和上下文压缩压缩逻辑会保留关键信息、丢弃冗余直接省 Token。业务逻辑层有 104 个斜杠命令和 60 多个工具。工具分几类文件操作FileReadTool、FileEditTool、执行环境BashTool、REPLTool、网络WebSearchTool、WebBrowserTool、AI 协作AgentTool、SendMessageTool、任务管理TaskCreateTool、TaskGetTool、MCPMCPTool、ListMcpResourcesTool。命令系统里/mcp管 MCP 服务器、/compact压缩上下文、/resume恢复会话、/skills管技能系统、/teammate做多 Agent 协作。用户交互层是 React Ink 渲染的终端 UI148 个组件支持 Vim 模式、消息气泡、代码高亮、进度条。自定义 Ink 渲染器有 52 个文件实现了布局系统、焦点管理、ANSI 颜色渲染、虚拟滚动列表。启动流程是bun run dev→dev-entry.ts→main.tsx800KB 主入口做初始化配置、加载 MCP、读历史、权限检查→launchRepl()→ 交互式终端界面。技术栈记一下TypeScript 5.x、Bun 1.3.5 或 Node.js 24、React 19 Ink 6.x、Commander.js 14.x、anthropic-ai/sdk0.80.0、modelcontextprotocol/sdk1.29.0。前置准备分三块。第一块是运行时。装 Buncurl -fsSL https://bun.sh/install | bash bun --version期望输出类似1.3.5。如果你用 Node.js确保 24但项目脚本默认走 Bun建议直接装 Bun。第二块是本地模型端点。本地模型要能提供兼容 Anthropic Messages API 的接口。常见做法是用 Ollama 或 vLLM 起一个服务再套一层协议转换或者直接用支持 Anthropic 协议的网关。这里不展开本地模型的具体部署重点放在“端点地址 Key 模型名”三件套怎么填。第三块是 TaoToken 统一 Key。TaoToken 提供统一的 API 通道把不同模型来源收敛到一个 Base URL 和一个 Key 上这样你切换模型只改 Model ID不用改地址和认证。注册和拿 Key 走官网# 打开官网注册并创建 API Key https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content拿到 Key 后API 端点是https://taotoken.net/api注意这个地址不加 UTM 参数直接用于程序请求。Key 的创建入口在控制台的 API Keys 页面https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content把这三样准备好本地模型端点或 TaoToken 的https://taotoken.net/api、对应的 API Key、你要用的 Model ID。后面配置就是围绕这三个值展开。3. 可复制配置环境变量、settings 与本地模型启动脚本这一节是全文最实操的部分所有片段都能直接复制。核心思路是用环境变量覆盖默认的 Anthropic 端点用--bare模式跳过 OAuth 认证。先看环境变量。Claude Code 读取ANTHROPIC_BASE_URL决定请求发往哪里读取ANTHROPIC_API_KEY做认证读取模型相关变量决定显示名和描述。写一个启动脚本start-local.sh#!/bin/bash # 本地模型 TaoToken 统一通道启动脚本 # 统一 API 通道地址TaoToken export ANTHROPIC_BASE_URLhttps://taotoken.net/api # 统一 Key从控制台 API Keys 页面获取 export ANTHROPIC_API_KEYsk-你的TaoTokenKey # 实际调用的模型 ID export LOCAL_MODEL_NAMEclaude-sonnet-4-5 # 终端里显示的模型名 export LOCAL_MODEL_NAME_DISPLAYTaoToken-Sonnet # 模型描述 export LOCAL_MODEL_DESCRIPTION通过 TaoToken 统一通道接入 # 启用本地模型模式 export ENABLE_LOCAL_MODELtrue echo 启动 Claude Code 本地模式... echo ANTHROPIC_BASE_URL: $ANTHROPIC_BASE_URL echo LOCAL_MODEL_NAME: $LOCAL_MODEL_NAME echo ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY:0:8}**** echo # --bare 跳过 OAuth 认证 bun run dev --bare如果你要接的是纯本地模型比如 Ollama 起的服务把ANTHROPIC_BASE_URL改成你的本地地址比如http://localhost:11434ANTHROPIC_API_KEY填本地服务要求的任意值或真实 KeyLOCAL_MODEL_NAME填本地模型名。接下来是 settings 文件。Claude Code 支持项目级和用户级 settings项目级放在.claude/settings.json用户级放在~/.claude/settings.json。项目级配置示例{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoTokenKey, LOCAL_MODEL_NAME: claude-sonnet-4-5, ENABLE_LOCAL_MODEL: true }, permissions: { allow: [ Read, Edit, Bash(git status), Bash(git diff) ], deny: [ Bash(rm -rf *), Bash(curl *) ] } }注意permissions里allow和deny的写法工具名加参数模式。deny优先级高于allow危险命令一定放deny。如果你用 Codex 或类似工具认证信息可能落在auth.json。Claude Code 开源版主要读环境变量但如果你同时维护多个工具建议把三件套统一记在一个地方{ base_url: https://taotoken.net/api, api_key: sk-你的TaoTokenKey, model_id: claude-sonnet-4-5 }Base URL、Key、Model ID 这三件套是接入任何兼容 Anthropic 协议端点的最小集合缺一不可。Base URL 决定请求去哪Key 决定能不能过认证Model ID 决定用哪个模型。如果你用 Cline 或带 MCP 的客户端MCP 配置里也要写全三件套。以 Cline 的 MCP 配置为例{ mcpServers: { taotoken: { command: npx, args: [-y, modelcontextprotocol/server-fetch], env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoTokenKey, MODEL_ID: claude-sonnet-4-5 } } } }CC Switch 这类多通道切换工具配置结构类似核心还是三件套。切换通道时只改 Base URL 和 KeyModel ID 按需改。配置写完后给脚本执行权限chmod x start-local.sh到这里配置就齐了。下一节验证请求是否真的通。4. 验证请求与工具调用确认本地模型真的跑通配置写完不代表通了必须做验证。验证分三层先验证端点可达再验证对话可用最后验证工具调用。第一层验证端点。用 curl 直接打 TaoToken 的 APIcurl -s https://taotoken.net/api/v1/messages \ -H x-api-key: sk-你的TaoTokenKey \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-5, max_tokens: 64, messages: [ {role: user, content: 回复两个字通了} ] }期望返回 JSONcontent数组里有文本。如果返回 401说明 Key 不对返回 404说明 Base URL 或路径不对返回模型不存在说明 Model ID 写错。第二层启动 Claude Code 做对话验证。跑启动脚本./start-local.sh进入终端界面后输入一句简单的话比如“列出当前目录的文件”。观察它是否调用 BashTool 执行ls是否把结果返回给你。这一步验证的是 API 客户端、会话管理、工具系统是否串起来了。第三层验证工具调用。在终端里输入读取 package.json 并告诉我项目名期望行为Claude Code 调用 FileReadTool 读文件解析 JSON返回项目名。如果它只是“假装”读了但没实际调用工具说明工具系统没接上检查ENABLE_LOCAL_MODEL和权限配置。再验证一个写操作在项目根目录创建一个 hello.txt内容写 local model works期望行为调用 FileEditTool 或 BashTool 创建文件。执行后你在终端外检查cat hello.txt期望输出local model works。这一步验证的是写权限和文件系统操作。验证 MCP 是否可用在终端里输入/mcp看是否列出已配置的 MCP 服务器。如果为空检查 settings 里的 MCP 配置路径。验证会话压缩输入/compact观察是否提示压缩上下文。这个功能在长对话后特别有用能省 Token。验证多 Agent输入/teammate看是否进入多 Agent 协作模式。这个功能依赖模型支持多轮工具调用本地小模型可能表现不稳定。三层验证都过了说明本地模型 TaoToken 通道 Claude Code 开源版这条链路是通的。接下来是排障。5. 常见报错排查401、local proxy failed、reading choices、OAuth这一节按真实报错来每个都给定位方法和修复动作。401 Unauthorized。最常见Key 问题。先确认ANTHROPIC_API_KEY有没有正确导出echo $ANTHROPIC_API_KEY如果为空说明脚本没 source 或环境变量没生效。如果非空但仍 401检查 Key 是否过期、是否复制时带了空格、是否用了错误的 Key 类型。TaoToken 的 Key 在控制台 API Keys 页面创建https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content重新生成一个 Key替换后重试。注意 curl 验证时用的是x-api-key头而 SDK 可能用Authorization: Bearer两种都要能过。local proxy failed。这个报错通常出现在你配了本地代理或本地模型端点但端点没起来。先确认本地服务在跑curl -s http://localhost:11434/api/tags如果连不上说明本地模型服务没启动。如果本地服务正常但 Claude Code 报 proxy failed检查ANTHROPIC_BASE_URL是否写成了http://localhost:11434但实际需要带路径比如http://localhost:11434/v1。另外确认没有系统级代理干扰NO_PROXY里加上localhost,127.0.0.1。reading choices of undefined。这个报错说明返回的 JSON 结构不符合预期。Claude Code 期望 Anthropic Messages API 格式content数组但你的端点返回了 OpenAI 格式choices数组。这是协议不匹配。解决方法是确认你的端点实现了 Anthropic 协议或者用一层转换把 OpenAI 格式转成 Anthropic 格式。TaoToken 的https://taotoken.net/api直接兼容 Anthropic 协议用这个地址不会出现该报错。OAuth 认证失败 / 卡在登录。开源版默认可能尝试 OAuth用--bare跳过bun run dev --bare如果仍卡住检查是否有残留的 OAuth token 文件清掉rm -rf ~/.claude/oauth*然后重新用--bare启动。注意--bare模式下必须提供ANTHROPIC_API_KEY否则没有认证方式。模型不存在 / model not found。Model ID 写错。确认你用的 Model ID 在 TaoToken 支持的列表里。可以先在模型对话页面测试https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content在页面里选模型发一条消息确认可用后把页面显示的 Model ID 复制到LOCAL_MODEL_NAME。工具调用不执行。模型返回了工具调用意图但没实际执行。检查两点一是权限配置里对应工具是否在allow列表二是模型是否支持 function calling。本地小模型可能不支持换支持工具调用的模型。上下文超限。长对话后报 token 超限。用/compact压缩或在 settings 里调小max_tokens。会话压缩功能会自动保留关键信息但手动触发更可控。排障的核心思路是分层定位先 curl 验证端点再验证认证再验证协议格式最后验证工具权限。每一层都有对应的检查命令不要跳步。6. 用 TaoToken 统一管理 API 通道与长期编码实践跑通之后真正省心的是通道管理。如果你同时用多个模型来源——本地 Ollama 做轻量补全、云端模型做复杂推理、团队共享的模型做代码审查——每个都配一套 Base URL 和 Key 会很乱。TaoToken 的价值是把这些收敛到一个 Base URL 和一个 Key 上切换模型只改 Model ID。统一通道的配置就是前面那三件套export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的TaoTokenKey export LOCAL_MODEL_NAMEclaude-sonnet-4-5想换模型只改LOCAL_MODEL_NAME。想换通道只改ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY。这种收敛让多环境切换变得简单开发机、测试机、CI 环境用同一套配置模板只替换 Key。长期编码场景下有几个实践值得坚持。第一把配置写进项目级.claude/settings.json不要只放环境变量。这样团队成员 clone 项目后只要填自己的 Key 就能跑Base URL 和 Model ID 统一。第二权限配置要收紧。deny列表里放危险命令allow列表里放常用安全命令。不要图省事全放开终端 Agent 能执行 Shell权限失控风险很高。第三善用/compact和/resume。长任务中途压缩上下文省 Token中断后用/resume恢复会话不用从头开始。第四MCP 扩展按需加载。/mcp管理服务器不用的关掉减少启动开销和权限面。第五多 Agent 协作/teammate适合拆解大任务但要注意模型能力。本地小模型在多 Agent 场景下容易跑偏复杂任务建议用能力更强的模型。如果你要把这套用于团队建议把 Coding Plan 作为长期编码和 Agent 任务的通道方案统一计费和配额管理https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content接入文档里有完整的协议说明和参数列表遇到协议细节问题时查这里https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content想快速验证某个模型是否可用用模型对话页面直接测https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content最后回到本地部署这件事。Claude Code 开源版的最大价值不是替代官方而是给你一个可读、可改、可接任意模型的终端 Agent 底座。架构四层清晰工具系统模块化MCP 扩展开放。你完全可以在它基础上加自己的工具、接自己的模型、做自己的权限策略。本地模型负责隐私敏感和低延迟场景统一通道负责复杂推理和多模型调度两者结合才是完整的本地编程助手方案。配置落地后建议先跑一周轻量任务观察哪些工具调用频繁、哪些模型响应稳定再逐步收紧权限和优化模型选择。终端 Agent 的调优是迭代出来的不是一次配好的。