在 Notebook 镜像中使用本地大模型部署 Claude Code 的方法

本文是一份镜像构建 + 使用配方：在 Notebook 镜像里安装 Claude Code 原生二进制，并通过包装脚本 claude-wrapper.sh 引导用户接入 Anthropic 兼容协议（/v1/messages）的大模型端点。镜像的在线构建与推送方式可参考 镜像在线构建和管理；私有仓库地址/账号配置参考 镜像仓库。

提示：平台官方 Notebook / Theia 镜像的 Dockerfile（仓库 images/jupyter-notebook/Dockerfile-ubuntu-base、Dockerfile-ubuntu-conda，以及 images/theia-new/Dockerfile-*）已内置下文"一、构建镜像"中的安装与包装脚本步骤，仓库也自带 images/jupyter-notebook/claude-wrapper.sh。若直接使用官方镜像，可跳过构建、直接进入"二、在 Notebook 中使用"；本文构建步骤主要面向自定义镜像或需要更新 Claude Code 版本的场景。

一、构建镜像

1. 安装 Claude Code 原生二进制

基于当前的镜像，在 Dockerfile 中加入以下内容，把 Claude Code 安装到镜像环境中：

# 安装 Claude Code 原生二进制
RUN BASE=https://downloads.claude.ai/claude-code-releases && \
    VERSION=$(curl -fsSL "$BASE/latest") && \
    if [ "$TARGETARCH" = "amd64" ]; then PLATFORM=linux-x64; else PLATFORM=linux-arm64; fi && \
    EXPECTED=$(curl -fsSL "$BASE/$VERSION/manifest.json" | python3 -c "import json,sys; print(json.load(sys.stdin)['platforms']['$PLATFORM']['checksum'])") && \
    curl -fsSL -o /usr/local/bin/claude.real "$BASE/$VERSION/$PLATFORM/claude" && \
    ACTUAL=$(sha256sum /usr/local/bin/claude.real | cut -d' ' -f1) && \
    [ "$EXPECTED" = "$ACTUAL" ] || { echo "checksum mismatch: $EXPECTED vs $ACTUAL" >&2; exit 1; } && \
    chmod +x /usr/local/bin/claude.real && \
    echo "claude $VERSION ($PLATFORM) installed"

2. 拷贝 claude-wrapper.sh

将 claude-wrapper.sh 拷贝到镜像中。为了后续运行方便，覆盖掉默认的 claude 命令：

# 拷贝 claude 包装脚本到 /usr/local/bin/claude
# (首次启动引导用户配置私有大模型 settings.json)
COPY claude-wrapper.sh /usr/local/bin/claude
RUN chmod +x /usr/local/bin/claude

二、在 Notebook 中使用

1. 创建 Notebook

构建完成镜像之后，在 Notebook 中点击添加 Notebook，镜像处填写您新构建的镜像名，并配置运行此 Notebook 所需要的 CPU、内存等。

2. 等待 Pod 启动

点击确定后，等待状态变为 Running。也可以点击 ContainerCreating 主动查看 Pod 当前的状态和日志情况。

3. 进入终端

Running 之后，您可点击进入 Notebook，然后点击终端。

4. 配置大模型

在命令行中输入 claude 命令启动脚本，按照脚本提示进行操作。

注意： API Key 会隐藏输入信息，您可以直接粘贴即可。

例如，以 DeepSeek 模型为例：

• 使用官方提供的 ANTHROPIC URL：https://api.deepseek.com/anthropic
• 使用官方推荐的模型名称：deepseek-v4-pro[1m]

例如 Qwen：

• ANTHROPIC URL：https://dashscope.aliyuncs.com/apps/anthropic
• Haiku 模型名：qwen3.6-flash
• Sonnet 模型名：qwen3.6-plus
• Opus 模型名：qwen3.6-plus

说明：以上模型名（deepseek-v4-pro[1m]、qwen3.6-*）与端点 URL 均为示例，请以你实际接入的大模型厂商提供的 Anthropic 兼容端点和模型名为准。原文此处第三行误写为"Haiku 模型名"，按包装脚本三个槽位（Haiku / Sonnet / Opus）应为 Opus 模型名，已据此更正。

填写完成后将自动启动 claude。

5. 开始对话

您可以在对话框中直接与 claude 对话，会使用您配置的大模型进行对话。

6. 配置持久化

此配置会在您的 CubeStudio 用户个人目录中留下配置文件，您重启此 Notebook 后仍然可以直接使用 claude。

7. 重置配置

若需要删除配置文件、重新进行配置，您可以在终端中运行以下命令删除可能存在的缓存文件，然后再次输入 claude 运行：

rm -f /mnt/admin/.settings.json
rm -f /root/.claude/settings.json

说明：上面的 /mnt/admin/.settings.json 中的 admin 是用户名示例，实际为 /mnt/$USERNAME/.settings.json（包装脚本中的 USER_SETTINGS）；/root/.claude/settings.json 对应 ${HOME:-/root}/.claude/settings.json（CLAUDE_SETTINGS）。

附：claude-wrapper.sh

#!/bin/bash
# Claude Code 启动包装脚本:自动从用户目录加载/生成 settings.json
# 后端必须是 Anthropic 兼容协议 (/v1/messages),例如官方 Claude API、
# Bedrock 代理或已做过协议转换的网关

set -e

# ---------- 1. 解析用户目录 ----------
USER_DIR="/mnt/${USERNAME}"
if [ -z "${USERNAME}" ] || [ ! -d "${USER_DIR}" ]; then
    if [ -d /mnt ] && [ "$(ls /mnt 2>/dev/null | wc -l)" = "1" ]; then
        USER_DIR="/mnt/$(ls /mnt)"
    else
        echo "[claude-wrapper] 无法定位用户目录 (\$USERNAME 未设置且 /mnt 下非唯一目录)" >&2
        exec /usr/local/bin/claude.real "$@"
    fi
fi

USER_SETTINGS="${USER_DIR}/.settings.json"
CLAUDE_DIR="${HOME:-/root}/.claude"
CLAUDE_SETTINGS="${CLAUDE_DIR}/settings.json"
mkdir -p "${CLAUDE_DIR}"

# ---------- 2. 已有配置 -> 直接复用 ----------
if [ -f "${USER_SETTINGS}" ]; then
    cp -f "${USER_SETTINGS}" "${CLAUDE_SETTINGS}"
    exec /usr/local/bin/claude.real "$@"
fi

# ---------- 3. 引导用户输入 ----------
echo "================================================================"
echo " 首次启动 Claude Code,请配置大模型接入参数 (Anthropic 兼容端点)"
echo " 配置完成后将保存到: ${USER_SETTINGS}"
echo "================================================================"

read -r -p "ANTHROPIC_BASE_URL (示例: https://api.anthropic.com): " BASE_URL
read -r -p "Haiku 模型名 (ANTHROPIC_DEFAULT_HAIKU_MODEL): " HAIKU_MODEL
read -r -p "Sonnet 模型名 (ANTHROPIC_DEFAULT_SONNET_MODEL): " SONNET_MODEL
read -r -p "Opus 模型名 (ANTHROPIC_DEFAULT_OPUS_MODEL): " OPUS_MODEL
read -r -s -p "API Key (ANTHROPIC_AUTH_TOKEN): " API_KEY
echo ""

if [ -z "${BASE_URL}" ] || [ -z "${HAIKU_MODEL}" ] || [ -z "${SONNET_MODEL}" ] || [ -z "${OPUS_MODEL}" ] || [ -z "${API_KEY}" ]; then
    echo "[claude-wrapper] 五项配置均不能为空,已退出。" >&2
    exit 1
fi

# 通过环境变量传给 python (heredoc 加单引号禁用 shell 展开),避免值含特殊字符破坏 JSON
ANTHROPIC_AUTH_TOKEN="${API_KEY}" \
ANTHROPIC_BASE_URL="${BASE_URL}" \
ANTHROPIC_DEFAULT_HAIKU_MODEL="${HAIKU_MODEL}" \
ANTHROPIC_DEFAULT_SONNET_MODEL="${SONNET_MODEL}" \
ANTHROPIC_DEFAULT_OPUS_MODEL="${OPUS_MODEL}" \
python3 - > "${USER_SETTINGS}" <<'PYEOF'
import json, os
print(json.dumps({
    "env": {
        "ANTHROPIC_AUTH_TOKEN": os.environ["ANTHROPIC_AUTH_TOKEN"],
        "ANTHROPIC_BASE_URL": os.environ["ANTHROPIC_BASE_URL"],
        "ANTHROPIC_DEFAULT_HAIKU_MODEL": os.environ["ANTHROPIC_DEFAULT_HAIKU_MODEL"],
        "ANTHROPIC_DEFAULT_SONNET_MODEL": os.environ["ANTHROPIC_DEFAULT_SONNET_MODEL"],
        "ANTHROPIC_DEFAULT_OPUS_MODEL": os.environ["ANTHROPIC_DEFAULT_OPUS_MODEL"],
        "API_TIMEOUT_MS": "3000000"
    }
}, indent=4, ensure_ascii=False))
PYEOF

chmod 600 "${USER_SETTINGS}"
cp -f "${USER_SETTINGS}" "${CLAUDE_SETTINGS}"
chmod 600 "${CLAUDE_SETTINGS}"

echo "[claude-wrapper] 配置已保存到 ${USER_SETTINGS}"
echo "[claude-wrapper] 下次输入 claude 将直接启动,无需再次配置。"
echo "------------------------------------------------------------------"
exec /usr/local/bin/claude.real "$@"

镜像构建与推送的更多说明，参见 镜像在线构建和管理 与 镜像仓库。Notebook 的创建、镜像保存等通用操作见 在线 IDE。