1. Ubuntu/Debian 部署 CC 开源版到底难在哪
CC 开源版（Claude-Code-Compiled）是一个跑在终端里的轻量代码助手，它把 Claude 生态的对话能力编译成单文件可执行包，靠 Bun 运行时驱动。适合谁？适合手里有一台 Ubuntu 或 Debian 服务器、想用命令行直接调模型写代码、又不想装一堆 Node 依赖的人。它是什么？一句话：把源码用 Bun 编译成 bundle.js，再用一个 alias 命令唤起，背后通过统一 API 通道请求模型。
我在 Debian 12 和 Ubuntu 22.04 上都走过一遍，真正卡人的不是编译，而是三件事：Bun 装完当前 shell 不认、第一次启动必然报错、以及 API Key 那一步选错就得删配置重来。这篇就按“从零到能跑”的顺序，把 Bun 安装、依赖拉取、TaoToken 统一 API 通道接入、settings.json 关键字段、启动验证和报错排查全部串起来，命令都能直接复制。
先说清楚整体链路：服务器装 unzip 和 Bun → 克隆 CC 仓库 → bun install 拉依赖 → bun build 编译 → 合并成 bundle.js → 配环境变量指向 TaoToken 的 API 地址 → 第一次启动生成配置 → 关掉引导 → 第二次启动选 yes 用配置里的 Key。每一步我都会给出实际命令和预期输出，你照着敲就行。
需要提前说明的是，CC 开源版本身只是个客户端壳子，它不绑定任何一家模型服务。你给它一个兼容 Anthropic 协议的 Base URL 和 Key，它就能工作。所以本文用 TaoToken 作为统一 API 通道来演示，这样你换模型时只改一个 Model ID，不用动客户端代码。下面正式开始。
2. 前置准备：Bun 运行时与 TaoToken API 通道
这一节解决两个前置：Bun 怎么在 Ubuntu/Debian 上装干净，以及 TaoToken 的 Key 和 Base URL 从哪来。Bun 是 CC 的运行时底座，没有它后面 bun install 和 bun build 全都跑不了。TaoToken 则是模型请求的出口，CC 通过它把对话转发给具体模型。
先装解压工具，CC 仓库拉下来后有些资源需要 unzip：
apt update apt install unzip curl git -y装 Bun。官方一键脚本会下载二进制并写入~/.bun：
curl -fsSL https://bun.sh/install | bash装完别急着敲 bun，先让当前 shell 认到它。脚本一般会往~/.bashrc追加 PATH，但当前会话还没加载：
source ~/.bashrc bun --version能打印出版本号（比如1.1.x）就对了。如果提示bun: command not found，手动补一行：
echo 'export BUN_INSTALL="$HOME/.bun"' >> ~/.bashrc echo 'export PATH="$BUN_INSTALL/bin:$PATH"' >> ~/.bashrc source ~/.bashrc接下来是 TaoToken 侧。打开官网 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 注册后进控制台，在 API Keys 页面创建一个 Key，复制保存。这个 Key 就是后面ANTHROPIC_API_KEY的值。Base URL 用https://taotoken.net/api，注意这个地址不带任何查询参数，直接填进环境变量即可。
模型 ID 怎么选？在模型对话页面能看到当前可用的模型列表，挑一个你需要的复制它的 ID，比如某个高速版或长上下文版。这个 ID 会填到ANTHROPIC_MODEL。如果你后面想换模型，只改这一个字段，CC 客户端不用重装。
提示：Key 只在创建时完整显示一次，建议创建后立刻存到密码管理器。控制台里可以随时吊销重建，但已发出的请求不会回滚。
到这里前置就齐了：Bun 能跑、Key 在手、Base URL 和 Model ID 明确。下一节进入真正的配置落地。
3. 可复制配置：CC 仓库构建与 settings.json 骨架
这一节是全文技术核心，包含克隆、编译、合并、环境变量、以及 settings.json 的关键字段。每一步都给完整命令，路径按/root/Claude-Code-Compiled演示，你换成自己的实际路径即可。
克隆仓库并进目录：
cd /root git clone https://github.com/roger2ai/Claude-Code-Compiled.git cd Claude-Code-Compiled拉依赖。Bun 会自动生成存根并修补 Commander.js，不用手动干预：
bun install编译源码到 dist 目录，指定 bun 目标：
bun build shims/macro.ts src/main.tsx --target=bun --outdir=./dist合并成单文件 bundle.js，并补一个执行入口：
cat dist/shims/macro.js dist/src/main.js > dist/bundle.js echo 'if (typeof main === "function") main().catch(e => { console.error(e); process.exit(1); });' >> dist/bundle.js确认 bundle.js 存在并记下绝对路径：
pwd ls -lh dist/bundle.js现在配环境变量。编辑~/.bashrc，在末尾追加下面这段。三件套必须齐全：Base URL、Key、Model ID，缺一个都会在请求时报错：
# TaoToken 统一 API 通道 export ANTHROPIC_BASE_URL="https://taotoken.net/api" export ANTHROPIC_API_KEY="你的TaoToken密钥" export ANTHROPIC_MODEL="你的模型ID" # CC 快捷命令，路径换成你的 bundle.js 绝对路径 alias claude='bun /root/Claude-Code-Compiled/dist/bundle.js'刷新生效：
source ~/.bashrc然后是 settings.json 骨架。CC 第一次启动会在~/.claude.json生成配置，但更规范的做法是维护一个~/.claude/settings.json，把模型和通道参数固化下来。新建目录和文件：
mkdir -p ~/.claude vim ~/.claude/settings.json写入以下 JSON 骨架，字段名与 CC 读取逻辑一致：
{ "hasCompletedOnboarding": true, "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "你的TaoToken密钥", "ANTHROPIC_MODEL": "你的模型ID" }, "permissions": { "allow": [] } }hasCompletedOnboarding设为 true 是跳过官方新手引导的关键，否则第一次启动会卡在引导流程。env块里的三个字段就是前面说的三件套，CC 启动时会优先读这里。permissions.allow先留空，后面按需加白名单。
注意：如果你同时改了
~/.bashrc和settings.json，两处的 Key 和 Base URL 要保持一致，避免一个对一个错导致 401。
配置写完，下一节验证请求是否真的通。
4. 启动验证：从报错到成功请求的完整过程
这一节验证配置是否生效。CC 的启动有个特点：第一次必然报错，这是设计使然，不是你的问题。理解这一点能省下大量排查时间。
第一次启动：
claude预期你会看到引导程序尝试联网并报错退出。这一步的作用是生成~/.claude.json。确认文件已生成：
ls -la ~/.claude.json如果前面已经在~/.claude/settings.json里写了hasCompletedOnboarding: true，可以直接进下一步。如果只有~/.claude.json，编辑它，在顶部加一行：
vim ~/.claude.json确保包含：
"hasCompletedOnboarding": true,第二次启动：
claude这次会正常进入工具界面，并询问是否使用配置文件中的 API Key。默认是 no，你必须手动选 yes 再回车。选错的话删掉配置重来：
rm -rf ~/.claude.json ~/.claude claude进入后发一条测试请求，比如让它解释一段代码或生成一个函数。观察返回是否正常。如果返回内容，说明 TaoToken 通道、Key、Model ID 三者都对上了。
想更直接地验证通道本身，可以绕过 CC 用 curl 打一次接口：
curl https://taotoken.net/api/v1/messages \ -H "x-api-key: 你的TaoToken密钥" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{ "model": "你的模型ID", "max_tokens": 64, "messages": [{"role": "user", "content": "ping"}] }'返回 JSON 里带content字段就说明通道通。这一步能把“客户端问题”和“通道问题”分开：curl 通但 CC 不通，问题在 CC 配置；curl 也不通，问题在 Key 或 Base URL。
实测下来，最容易出问题的是 Model ID 拼写和 Base URL 末尾多斜杠。Base URL 填https://taotoken.net/api即可，不要自己加/v1，客户端会拼接路径。
5. 常见报错排查：401、local proxy failed 与 reading choices
这一节对照真实报错逐个拆。CC 部署阶段能遇到的错误基本就这几类，按现象对号入座。
401 Unauthorized：Key 无效或没被读到。先确认settings.json和~/.bashrc里的 Key 一致，再确认没有多余空格或换行。用上一节的 curl 单独验证 Key。如果 curl 也 401，去 TaoToken 控制台确认 Key 是否被吊销、额度是否耗尽。
local proxy failed / connection refused：客户端尝试连本地代理但没起来。检查ANTHROPIC_BASE_URL是否被误设成http://localhost:xxxx。正确值应是https://taotoken.net/api。另外确认服务器出网正常：
curl -I https://taotoken.net/apireading choices / undefined is not an object：这类多半是响应结构不符合预期，常见于 Model ID 填错，服务端返回了错误对象而客户端按正常结构解析。核对ANTHROPIC_MODEL与控制台模型列表完全一致，大小写和连字符都不能差。
OAuth / 引导卡住：第一次启动的引导流程需要跳过。确认hasCompletedOnboarding为 true，且写在 JSON 顶层。如果文件被写坏，直接删掉重建：
rm -rf ~/.claude.json ~/.claudebun: command not found：Bun 的 PATH 没进当前 shell。重跑source ~/.bashrc，或按第 2 节手动补 PATH。
bundle.js 找不到：alias 里的路径不是绝对路径。用pwd确认项目位置，把 alias 改成完整路径。
排查顺序建议：先 curl 验通道 → 再验环境变量 → 最后验 CC 配置。这样能快速定位是通道、配置还是客户端的问题。三件套（Base URL + Key + Model ID）任何一处不对都会在这几类报错里体现。
6. 后续接入与命令速查
跑通之后，日常就是claude一条命令唤起。想换模型只改ANTHROPIC_MODEL，想换通道只改ANTHROPIC_BASE_URL，客户端不用重装。如果你要长期做编码或跑 Agent 任务，可以了解 Coding Plan，按用量规划更省心；需要管理多个 Key 就去 API Keys 页面；想先试模型效果可以直接在模型对话里聊几句；接入细节和字段说明看接入文档。
命令速查留一份，方便复制：
# 装 Bun curl -fsSL https://bun.sh/install | bash && source ~/.bashrc # 构建 CC cd /root/Claude-Code-Compiled bun install bun build shims/macro.ts src/main.tsx --target=bun --outdir=./dist cat dist/shims/macro.js dist/src/main.js > dist/bundle.js echo 'if (typeof main === "function") main().catch(e => { console.error(e); process.exit(1); });' >> dist/bundle.js # 启动 claude最后提醒一句：~/.claude/settings.json里的 Key 是明文，服务器多人使用时注意文件权限，chmod 600 ~/.claude/settings.json收一下。配置改完记得source ~/.bashrc，不然当前会话读的还是旧值。
