Claude Code 安装与配置完全指南：多平台安装到接入国内模型

macOS 安装教程

系统要求

操作系统：macOS 13.0 或更高版本

处理器：Apple Silicon (M1/M2/M3/M4) 或 Intel

内存：至少 4GB RAM

磁盘空间：至少 500MB 可用空间

运行环境：Node.js 22+（npm 安装方式需要）

其他：Git（推荐）

网络：需要互联网连接

第一步：安装 Claude Code

方式一：官方脚本（国内可能 403）

curl -fsSL https://claude.ai/install.sh | bash

方式二：npm 安装（推荐，国内可用）

npm config set registry https://registry.npmmirror.com
npm install -g @anthropic-ai/claude-code

⚠️ 使用 npm 安装时不要加 sudo，以免出现权限问题。

验证安装：

claude --version

显示版本号说明安装成功

第二步：运行诊断

claude doctor

检查安装是否完整，有问题会提示你。运行后会显示诊断结果，按 Enter 键退出。

⚠️ claude doctor 最后会等待你按 Enter 才退出，如果超时未响应会自动结束。

第三步：验证安装

claude --version

应该显示 Claude Code v2.x.x

💡 关于登录：启动 Claude Code 时会提示 Not logged in · Run /login，这是登录 Anthropic 官方账号（需要海外信用卡）。国内用户使用 ccr + MiMo 方案不需要登录，直接跳过即可。

第四步：开始使用

在项目目录中启动 Claude Code：

cd your-project
claude

单次查询：

claude -p "帮我写一个 Python 脚本"

🔧 接入国内模型（通过 ccr 格式转换）

⚠️ Claude Code 使用 Anthropic API 格式（/v1/messages），而国内模型（MiMo、DeepSeek、Kimi 等）只支持 OpenAI 格式（/v1/chat/completions）。两者格式不兼容，不能直接接入。

💡 解决方案：使用 ccr（Claude Code Router） 作为格式转换代理，将 Claude Code 的 Anthropic 请求自动转换为 OpenAI 格式，再转发到国内模型。

前提条件

• 已完成 Claude Code 安装
• 有国内模型的 API Key（以小米 MiMo 为例）

第一步：安装 ccr

npm install -g claude-code-router

验证安装：

ccr --version

应该显示 2.0.0 或更高版本

第二步：配置 ccr

创建配置文件（以小米 MiMo 为例，其他模型见下方说明）：

复制以下整个代码块（从 mkdir 到 EOF），粘贴到终端后按回车执行：

💡 这是一个完整的命令块，复制后直接粘贴到终端，按一次回车即可。如果手动输入，每输完一行按一次回车，最后输入 EOF 后也要按回车。

mkdir -p ~/.claude-code-router
cat > ~/.claude-code-router/config-router.json << 'EOF'
{
  "server": {
    "port": 3456,
    "host": "127.0.0.1"
  },
  "routing": {
    "rules": {
      "default": { "provider": "CUSTOM", "model": "你的模型名称" },
      "background": { "provider": "CUSTOM", "model": "你的模型名称" },
      "thinking": { "provider": "CUSTOM", "model": "你的模型名称" },
      "longcontext": { "provider": "CUSTOM", "model": "你的模型名称" },
      "search": { "provider": "CUSTOM", "model": "你的模型名称" }
    },
    "defaultProvider": "CUSTOM",
    "providers": {
      "CUSTOM": {
        "type": "openai",
        "endpoint": "你的API地址",
        "authentication": {
          "type": "bearer",
          "credentials": {
            "apiKey": "sk-你的API Key"
          }
        },
        "settings": {
          "categoryMappings": {
            "default": true,
            "background": true,
            "thinking": true,
            "longcontext": true,
            "search": true
          },
          "models": ["你的模型名称"],
          "defaultModel": "你的模型名称"
        }
      }
    }
  }
}
EOF

按 Enter 确认输入。

你需要修改以下 4 个值（复制命令后替换对应位置）：

sed -i -e 's|CUSTOM|xiaomi|g' \
       -e 's|你的API地址|https://api.xiaomimimo.com/v1/chat/completions|g' \
       -e 's|你的模型名称|mimo-v2.5|g' \
       -e 's|sk-你的API Key|sk-你的真实Key|g' \
       ~/.claude-code-router/config-router.json

常用模型配置参考：

💡 把表格中的 4 个值替换到 sed 命令里，一条命令搞定。

第三步：启动 ccr

安装 screen（如果没有）：

sudo apt install screen -y

创建 screen 会话并启动 ccr：

screen -S ccr

在 screen 会话中执行：

# 如果有旧进程占用端口，先杀掉
pkill -9 -f "ccr" 2>/dev/null || true
sleep 1

# 启动 ccr
ccr start

看到启动日志后，按 Ctrl + A 然后按 D 分离会话（detach）。

💡 分离后 ccr 会在后台持续运行，关掉终端也不会停止。重新连接用 screen -r ccr。

验证 ccr 是否正常：

curl -s http://127.0.0.1:3456/health

应该看到 "overall":"ok" 或 "overall":"degraded"（codewhisperer 显示 false 是正常的）。

第四步：测试 ccr 格式转换

curl -s http://127.0.0.1:3456/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: test" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 100,
    "messages": [{"role": "user", "content": "1+1=?"}]
  }'

如果返回包含 "content" 的 JSON 响应（且没有 error 字段），说明 ccr 格式转换正常工作。

第五步：配置 Claude Code 连接 ccr

设置环境变量（让 Claude Code 的请求走 ccr 转发到 MiMo）：

export ANTHROPIC_BASE_URL="http://127.0.0.1:3456"
export ANTHROPIC_API_KEY="***"

💡 建议将这两行写入 ~/.bashrc，避免每次都要重新输入：

echo 'export ANTHROPIC_BASE_URL="http://127.0.0.1:3456"' >> ~/.bashrc
echo 'export ANTHROPIC_API_KEY="***"' >> ~/.bashrc
source ~/.bashrc

第六步：首次启动 Claude Code

claude

首次启动会依次出现四个提示：

1. 选择主题 → 直接按 回车 选择默认的 Dark mode
2. 检测到 API Key → 选择 1. Yes 使用当前环境变量中的 Key
3. 安全须知（Security notes）→ 按 回车 继续
4. 工作区信任确认 → 选择 1. Yes, I trust this folder 然后按回车

进入 Claude Code 后，需要先退出再继续后续操作。按 Ctrl + C 两次即可退出，或者输入 /exit 回车。

第七步：验证完整链路

测试 Claude Code 通过 ccr 调用 MiMo：

claude -p "1+1等于几？"

完整链路示意

用户输入
↓
Claude Code（Anthropic 格式 /v1/messages）
↓
ccr 代理（127.0.0.1:3456，自动转换格式）
↓
MiMo API（OpenAI 格式 /v1/chat/completions）
↓
返回结果

🔧 对接飞书

⚠️ Claude Code 官方不支持飞书，但社区做了桥接工具。以下使用 larkcc 实现（经过实测验证）。

前提条件

• 已完成 Claude Code 安装
• 已接入模型（通过 ccr 或直接使用 Anthropic 官方 API）
• 有飞书开放平台的应用凭证

第一步：安装 larkcc

npm install -g larkcc

验证安装：

larkcc --version

应该显示 0.13.0 或更高版本

第二步：创建飞书应用

1. 打开 飞书开放平台
2. 点击 创建企业自建应用
3. 填写应用名称（如"Claude Code 助手"）和描述
4. 创建完成后，在 凭证与基础信息 页面获取 App ID 和 App Secret

第三步：配置飞书应用权限

在飞书开发者后台，进入你的应用，依次配置：

1. 启用机器人能力

左侧菜单 → 应用能力 → 机器人 → 开启

2. 添加权限

左侧菜单 → 权限管理 → 搜索并开通以下权限：

3. 配置事件订阅

左侧菜单 → 事件与回调 → 订阅方式 → 选择 使用长连接接收事件/回调

然后添加事件：接收消息 im.message.receive_v1

4. 发布应用

左侧菜单 → 版本管理与发布 → 创建版本 → 填写版本号和更新说明 → 提交审核

⚠️ 应用必须发布后才能正常使用。发布后机器人状态应为 已激活（activate_status=1）。

第四步：配置 larkcc

⚠️ larkcc --setup 目前有 bug，需要手动创建配置文件。

创建配置目录：

mkdir -p ~/.larkcc

创建配置文件（先用占位符，后面再替换 open_id）：

复制以下整个代码块，粘贴到终端后按回车执行：

cat > ~/.larkcc/config.yml << 'EOF'
feishu:
  app_id: "你的 App ID"
  app_secret: "你的 App Secret"
  owner_open_id: "ou_占位符后面替换"
EOF

将 你的 App ID 和 你的 App Secret 替换为真实值。按 Enter 确认。

第五步：启动 larkcc 获取 open_id

创建 screen 会话并启动 larkcc：

screen -S larkcc-temp

在 screen 会话中执行：

larkcc

终端会实时显示日志。打开飞书，给机器人发一条消息（如"你好"）。

你会在终端看到类似这样的日志：

⚠ Ignored message from unknown user: ou_2ae3ade3e7a4fdefd5d878c797a7622f

ou_ 开头的那串就是你的 open_id，复制下来。按 Ctrl + C 停止 larkcc。

第六步：更新配置文件

用你的真实 open_id 替换占位符：

sed -i 's/ou_占位符后面替换/你的真实open_id/' ~/.larkcc/config.yml

验证替换是否成功：

cat ~/.larkcc/config.yml

第七步：启动 larkcc（后台常驻）

先停止之前临时启动的 larkcc（在临时 screen 会话中按 Ctrl + C）：

screen -r larkcc-temp
# 按 Ctrl + C 停止，然后按 Ctrl + A 再按 D 分离
# 或者直接终止：
screen -X -S larkcc-temp quit

macOS 自带 screen，无需安装。创建 screen 会话并启动 larkcc：

screen -S larkcc

在 screen 会话中执行：

larkcc

看到 ✅ Feishu connected! 后，按 Ctrl + A 然后按 D 分离会话（detach）。

💡 分离后 larkcc 会在后台持续运行，关掉终端也不会停止。重新连接用 screen -r larkcc。

第八步：验证飞书连接

在飞书中给机器人发一条消息（如"你好"），如果收到回复说明连接成功。

注意事项

• 服务运行时电脑需保持开机和联网状态
• getBotInfo failed 错误可忽略，不影响通信
• 如需群聊支持，需额外添加 im:message.group_at_msg:readonly 权限
• 单聊和群聊共用同一个 Claude Code session

❓ 常见问题

Q: `claude` 命令找不到？

检查安装路径是否在 PATH 中：

macOS/Linux：

echo $PATH | grep -o "$HOME/.local/bin" || echo "PATH not set"
export PATH="$HOME/.local/bin:$PATH"

Windows：

where claude

如果找不到，检查系统 PATH 环境变量。

Q: 登录失败怎么办？

rm -rf ~/.claude
claude

Q: 如何更新到最新版？

claude update

Q: 如何查看配置？

claude config list

Q: ccr 启动后端口被占用？

lsof -i :3456

ccr start -p 3457

Q: Claude Code 回复报 404 错误？

检查 ANTHROPIC_BASE_URL 是否正确指向 ccr：

echo $ANTHROPIC_BASE_URL

Q: 飞书机器人没有反应？

1. 确认应用已发布且状态为"已激活"
2. 确认事件订阅方式为"长连接"
3. 确认已订阅 im.message.receive_v1 事件
4. 检查 larkcc 终端是否有错误输出

📚 常用管理命令速查

Windows 安装教程

系统要求

操作系统：Windows 10 (1809+) 或更高版本

处理器：x64 架构 CPU

内存：至少 4GB RAM

磁盘空间：至少 500MB 可用空间

运行环境：Node.js 22+（npm 安装方式需要）

其他：Git（推荐）

网络：需要互联网连接

第一步：安装 Claude Code

方式一：官方脚本（国内可能 403）

⚠️ Windows 用户请以管理员身份运行 PowerShell，否则可能遇到权限问题。

打开 PowerShell（以管理员身份运行），执行：

irm https://claude.ai/install.ps1 | iex

方式二：npm 安装（推荐，国内可用）

npm config set registry https://registry.npmmirror.com
npm install -g @anthropic-ai/claude-code

⚠️ 使用 npm 安装时不要加 sudo，以免出现权限问题。

验证安装：

claude --version

显示版本号说明安装成功

第二步：运行诊断

claude doctor

检查安装是否完整，有问题会提示你。

第三步：验证安装

claude --version

应该显示 Claude Code v2.x.x

💡 关于登录：启动 Claude Code 时会提示 Not logged in · Run /login，这是登录 Anthropic 官方账号（需要海外信用卡）。国内用户使用 ccr + MiMo 方案不需要登录，直接跳过即可。

第四步：开始使用

在项目目录中启动 Claude Code：

cd your-project
claude

单次查询：

claude -p "帮我写一个 Python 脚本"

💡 推荐安装 Git for Windows，这样 Claude Code 可以使用 Bash 工具。如果没有安装 Git，Claude Code 会使用 PowerShell 作为替代。

💡 如果你更习惯 Linux 环境，或者原生方式遇到问题，可以用 WSL2。

第一步：安装 WSL2

打开 PowerShell（以管理员身份运行），执行：

wsl --install

重启电脑后，从开始菜单打开 Ubuntu，设置用户名和密码。

第二步：安装 Claude Code

在 Ubuntu 终端中执行：

curl -fsSL https://claude.ai/install.sh | bash

npm config set registry https://registry.npmmirror.com
npm install -g @anthropic-ai/claude-code

第三步：验证与配置

claude --version

claude doctor

claude

WSL2 方式和 Linux 安装完全一致，后续步骤参考 Linux 教程。

🔧 接入国内模型（通过 ccr 格式转换）

⚠️ Claude Code 使用 Anthropic API 格式（/v1/messages），而国内模型（MiMo、DeepSeek、Kimi 等）只支持 OpenAI 格式（/v1/chat/completions）。两者格式不兼容，不能直接接入。

💡 解决方案：使用 ccr（Claude Code Router） 作为格式转换代理，将 Claude Code 的 Anthropic 请求自动转换为 OpenAI 格式，再转发到国内模型。

前提条件

• 已完成 Claude Code 安装
• 有国内模型的 API Key（以小米 MiMo 为例）

第一步：安装 ccr

npm install -g claude-code-router

验证安装：

ccr --version

应该显示 2.0.0 或更高版本

第二步：配置 ccr

创建配置文件（以小米 MiMo 为例，其他模型见下方说明）：

复制以下整个代码块（从 mkdir 到 EOF），粘贴到终端后按回车执行：

💡 这是一个完整的命令块，复制后直接粘贴到终端，按一次回车即可。如果手动输入，每输完一行按一次回车，最后输入 EOF 后也要按回车。

mkdir -p ~/.claude-code-router
cat > ~/.claude-code-router/config-router.json << 'EOF'
{
  "server": {
    "port": 3456,
    "host": "127.0.0.1"
  },
  "routing": {
    "rules": {
      "default": { "provider": "CUSTOM", "model": "你的模型名称" },
      "background": { "provider": "CUSTOM", "model": "你的模型名称" },
      "thinking": { "provider": "CUSTOM", "model": "你的模型名称" },
      "longcontext": { "provider": "CUSTOM", "model": "你的模型名称" },
      "search": { "provider": "CUSTOM", "model": "你的模型名称" }
    },
    "defaultProvider": "CUSTOM",
    "providers": {
      "CUSTOM": {
        "type": "openai",
        "endpoint": "你的API地址",
        "authentication": {
          "type": "bearer",
          "credentials": {
            "apiKey": "sk-你的API Key"
          }
        },
        "settings": {
          "categoryMappings": {
            "default": true,
            "background": true,
            "thinking": true,
            "longcontext": true,
            "search": true
          },
          "models": ["你的模型名称"],
          "defaultModel": "你的模型名称"
        }
      }
    }
  }
}
EOF

按 Enter 确认输入。

你需要修改以下 4 个值（复制命令后替换对应位置）：

sed -i -e 's|CUSTOM|xiaomi|g' \
       -e 's|你的API地址|https://api.xiaomimimo.com/v1/chat/completions|g' \
       -e 's|你的模型名称|mimo-v2.5|g' \
       -e 's|sk-你的API Key|sk-你的真实Key|g' \
       ~/.claude-code-router/config-router.json

常用模型配置参考：

💡 把表格中的 4 个值替换到 sed 命令里，一条命令搞定。

第三步：启动 ccr

安装 screen（如果没有）：

sudo apt install screen -y

创建 screen 会话并启动 ccr：

screen -S ccr

在 screen 会话中执行：

# 如果有旧进程占用端口，先杀掉
pkill -9 -f "ccr" 2>/dev/null || true
sleep 1

# 启动 ccr
ccr start

看到启动日志后，按 Ctrl + A 然后按 D 分离会话（detach）。

💡 分离后 ccr 会在后台持续运行，关掉终端也不会停止。重新连接用 screen -r ccr。

验证 ccr 是否正常：

curl -s http://127.0.0.1:3456/health

应该看到 "overall":"ok" 或 "overall":"degraded"（codewhisperer 显示 false 是正常的）。

第四步：测试 ccr 格式转换

curl -s http://127.0.0.1:3456/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: test" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 100,
    "messages": [{"role": "user", "content": "1+1=?"}]
  }'

如果返回包含 "content" 的 JSON 响应（且没有 error 字段），说明 ccr 格式转换正常工作。

第五步：配置 Claude Code 连接 ccr

设置环境变量（让 Claude Code 的请求走 ccr 转发到 MiMo）：

export ANTHROPIC_BASE_URL="http://127.0.0.1:3456"
export ANTHROPIC_API_KEY="***"

💡 建议将这两行写入 ~/.bashrc，避免每次都要重新输入：

echo 'export ANTHROPIC_BASE_URL="http://127.0.0.1:3456"' >> ~/.bashrc
echo 'export ANTHROPIC_API_KEY="***"' >> ~/.bashrc
source ~/.bashrc

第六步：首次启动 Claude Code

claude

首次启动会依次出现四个提示：

1. 选择主题 → 直接按 回车 选择默认的 Dark mode
2. 检测到 API Key → 选择 1. Yes 使用当前环境变量中的 Key
3. 安全须知（Security notes）→ 按 回车 继续
4. 工作区信任确认 → 选择 1. Yes, I trust this folder 然后按回车

进入 Claude Code 后，需要先退出再继续后续操作。按 Ctrl + C 两次即可退出，或者输入 /exit 回车。

第七步：验证完整链路

测试 Claude Code 通过 ccr 调用 MiMo：

claude -p "1+1等于几？"

完整链路示意

用户输入
↓
Claude Code（Anthropic 格式 /v1/messages）
↓
ccr 代理（127.0.0.1:3456，自动转换格式）
↓
MiMo API（OpenAI 格式 /v1/chat/completions）
↓
返回结果

🔧 对接飞书

⚠️ Claude Code 官方不支持飞书，但社区做了桥接工具。以下使用 larkcc 实现（经过实测验证）。

前提条件

• 已完成 Claude Code 安装
• 已接入模型（通过 ccr 或直接使用 Anthropic 官方 API）
• 有飞书开放平台的应用凭证

第一步：安装 larkcc

npm install -g larkcc

验证安装：

larkcc --version

应该显示 0.13.0 或更高版本

第二步：创建飞书应用

1. 打开 飞书开放平台
2. 点击 创建企业自建应用
3. 填写应用名称（如"Claude Code 助手"）和描述
4. 创建完成后，在 凭证与基础信息 页面获取 App ID 和 App Secret

第三步：配置飞书应用权限

在飞书开发者后台，进入你的应用，依次配置：

1. 启用机器人能力

左侧菜单 → 应用能力 → 机器人 → 开启

2. 添加权限

左侧菜单 → 权限管理 → 搜索并开通以下权限：

3. 配置事件订阅

左侧菜单 → 事件与回调 → 订阅方式 → 选择 使用长连接接收事件/回调

然后添加事件：接收消息 im.message.receive_v1

4. 发布应用

左侧菜单 → 版本管理与发布 → 创建版本 → 填写版本号和更新说明 → 提交审核

⚠️ 应用必须发布后才能正常使用。发布后机器人状态应为 已激活（activate_status=1）。

第四步：配置 larkcc

⚠️ larkcc --setup 目前有 bug，需要手动创建配置文件。

创建配置目录：

mkdir -p ~/.larkcc

创建配置文件（先用占位符，后面再替换 open_id）：

复制以下整个代码块，粘贴到终端后按回车执行：

cat > ~/.larkcc/config.yml << 'EOF'
feishu:
  app_id: "你的 App ID"
  app_secret: "你的 App Secret"
  owner_open_id: "ou_占位符后面替换"
EOF

将 你的 App ID 和 你的 App Secret 替换为真实值。按 Enter 确认。

第五步：启动 larkcc 获取 open_id

创建 screen 会话并启动 larkcc：

screen -S larkcc-temp

在 screen 会话中执行：

larkcc

终端会实时显示日志。打开飞书，给机器人发一条消息（如"你好"）。

你会在终端看到类似这样的日志：

⚠ Ignored message from unknown user: ou_2ae3ade3e7a4fdefd5d878c797a7622f

ou_ 开头的那串就是你的 open_id，复制下来。按 Ctrl + C 停止 larkcc。

第六步：更新配置文件

用你的真实 open_id 替换占位符：

sed -i 's/ou_占位符后面替换/你的真实open_id/' ~/.larkcc/config.yml

验证替换是否成功：

cat ~/.larkcc/config.yml

第七步：启动 larkcc（保持运行）

先停止之前临时启动的 larkcc（按 Ctrl + C）。

Windows 没有 screen，有两种方式保持 larkcc 运行：

方式一：单独开一个终端窗口（最简单）

新建一个终端窗口，运行：

larkcc

保持这个窗口不要关闭，机器人就能持续运行。

方式二：后台运行（关窗口不停）

start /b larkcc > larkcc.log 2>&1

查看日志：

type larkcc.log

第八步：验证飞书连接

在飞书中给机器人发一条消息（如"你好"），如果收到回复说明连接成功。

注意事项

• 服务运行时电脑需保持开机和联网状态
• getBotInfo failed 错误可忽略，不影响通信
• 如需群聊支持，需额外添加 im:message.group_at_msg:readonly 权限
• 单聊和群聊共用同一个 Claude Code session

❓ 常见问题

Q: `claude` 命令找不到？

检查安装路径是否在 PATH 中：

macOS/Linux：

echo $PATH | grep -o "$HOME/.local/bin" || echo "PATH not set"
export PATH="$HOME/.local/bin:$PATH"

Windows：

where claude

如果找不到，检查系统 PATH 环境变量。

Q: 登录失败怎么办？

rm -rf ~/.claude
claude

Q: 如何更新到最新版？

claude update

Q: 如何查看配置？

claude config list

Q: ccr 启动后端口被占用？

lsof -i :3456

ccr start -p 3457

Q: Claude Code 回复报 404 错误？

检查 ANTHROPIC_BASE_URL 是否正确指向 ccr：

echo $ANTHROPIC_BASE_URL

Q: 飞书机器人没有反应？

1. 确认应用已发布且状态为"已激活"
2. 确认事件订阅方式为"长连接"
3. 确认已订阅 im.message.receive_v1 事件
4. 检查 larkcc 终端是否有错误输出

📚 常用管理命令速查