Docker 容器内配置 AI 编程 CLI 完整指南

用户1357399925660
6 阅读4分钟

Docker 容器内配置 AI 编程 CLI 完整指南

适用于 VS Code Dev Containers 环境，手把手教你配置 Claude Code、Codex、 Gemini 三大主流 AI CLI 及 MCP 服务。

一、什么是 MCP？

MCP (Model Context Protocol) 是一个开放协议，让 AI 模型能够连接外部工具和服务：

MCP 服务功能常用场景
Filesystem读写本地文件代码生成、文件操作
GitHub操作 GitHub 仓库代码审查、PR 管理
Context7语义记忆跨会话上下文保持
Fetch网页抓取技术调研、文档获取

二、环境准备

2.1 目录结构

项目根目录/
├── .devcontainer/
│   ├── devcontainer.json
│   └── Dockerfile
├── docker-config/
│   ├── claude/config.json
│   ├── codex/config.toml
│   └── gemini/settings.json
└── docker-compose.yml

2.2 基础镜像要求

FROM node:20-bookworm

# 安装基础工具
RUN apt-get update && apt-get install -y \
    git \
    curl \
    && rm -rf /var/lib/apt/lists/*

三、核心避坑指南（必读）

坑 1：Claude 配置文件被屏蔽

问题：Claude CLI 启动时会自动生成 ~/.claude.json，覆盖你挂载的配置。

解决：在 Dockerfile 中建立软链接：

RUN rm -f /home/node/.claude.json \
    && ln -sf /home/node/.claude/config.json /home/node/.claude.json

坑 2：Gemini 超时

问题：Gemini 对 MCP 工具启动超时非常敏感，使用 npx 会超时。

解决：全局安装工具 + 本地命令调用：

RUN npm install -g mcp-fetch-server

# 配置中使用
# "command": "mcp-fetch-server"  # 而非 "npx -y mcp-fetch-server"

坑 3：Fetch 包名错误

问题：官方文档推荐的 Python 版 Fetch 在 Node 容器中难以运行。

解决：使用 Node.js 版本：

npm install -g mcp-fetch-server  # 而非 pip install mcp-fetch

坑 4：Codex 格式错误

问题：TOML 配置缺少 type = "stdio" 字段。

解决：确保每个 MCP 服务配置都包含：

[mcp_servers.filesystem]
type = "stdio"  # 必填
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]

四、安装 CLI 工具

4.1 修改 Dockerfile

在 .devcontainer/Dockerfile 中添加：

# 安装 AI CLI 工具
RUN npm install -g \
    @anthropic-ai/claude-code \
    @openai/codex \
    @google/gemini-cli

# 安装 MCP 服务
RUN npm install -g \
    @modelcontextprotocol/server-filesystem \
    @modelcontextprotocol/server-github \
    @upstash/context7-mcp \
    mcp-fetch-server

# 修复 Claude 配置软链接
RUN rm -f /home/node/.claude.json \
    && ln -sf /home/node/.claude/config.json /home/node/.claude.json

4.2 重建容器

在 VS Code 中按 F1 -> Dev Containers: Rebuild Container

五、获取 API Token

5.1 Claude ( Anthropic )

  1. 访问 Anthropic Console
  2. 创建 API Key
  3. 设置环境变量：
export ANTHROPIC_AUTH_TOKEN="sk-ant-..."

5.2 Codex (OpenAI)

  1. 访问 OpenAI Platform
  2. 创建 API Key
  3. 设置环境变量：
export OPENAI_API_KEY="sk-..."

5.3 Gemini (Google)

  1. 访问 Google AI Studio
  2. 创建 API Key
  3. 设置环境变量：
export GEMINI_API_KEY="AI..."

5.4 GitHub (MCP 需要)

  1. 进入 GitHub Settings -> Developer settings -> Personal access tokens
  2. 生成 Classic Token，勾选 repo 和 user 权限
  3. Token 格式：ghp_...

六、配置文件详解

6.1 Claude Code 配置

文件：docker-config/claude/config.json

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_你的Token"
      }
    },
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"]
    },
    "fetch": {
      "command": "mcp-fetch-server",
      "args": []
    }
  }
}

挂载配置：

# docker-compose.yml
services:
  app:
    volumes:
      - ./docker-config/claude:/home/node/.claude:ro

6.2 Codex 配置

文件：docker-config/codex/config.toml

# Filesystem
[mcp_servers.filesystem]
type = "stdio"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]

# GitHub
[mcp_servers.github]
type = "stdio"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]

[mcp_servers.github.env]
GITHUB_PERSONAL_ACCESS_TOKEN = "ghp_你的Token"

# Context7
[mcp_servers.context7]
type = "stdio"
command = "npx"
args = ["-y", "@upstash/context7-mcp@latest"]

# Fetch (本地直连)
[mcp_servers.fetch]
type = "stdio"
command = "mcp-fetch-server"
args = []

挂载配置：

volumes:
  - ./docker-config/codex:/home/node/.codex:ro

6.3 Gemini 配置

文件：docker-config/gemini/settings.json

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_你的Token"
      }
    },
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"]
    },
    "fetch": {
      "command": "mcp-fetch-server",
      "args": []
    }
  }
}

挂载配置：

volumes:
  - ./docker-config/gemini:/home/node/.gemini-cli:ro

七、验证配置

7.1 验证 Claude

claude --version
claude -p "列出当前目录文件"

7.2 验证 Codex

codex --version
codex --quiet "列出当前目录"

7.3 验证 Gemini

gemini --version
gemini -p "列出当前目录文件"

八、常见问题

Q1: 配置文件不生效？

检查：

  1. 软链接是否建立成功：ls -la ~/.claude.json
  2. 挂载路径是否正确
  3. 是否重建了容器

Q2: MCP 服务启动超时？

检查：

  1. 是否全局安装了工具
  2. 是否使用本地命令而非 npx
  3. 检查工具是否可用：which mcp-fetch-server

Q3: GitHub 认证失败？

检查：

  1. Token 是否有 repo 和 user 权限
  2. Token 是否过期
  3. 环境变量是否正确传递

Q4: 端口冲突？

某些 MCP 服务可能需要特定端口，确保不被占用：

lsof -i :3000  # 检查端口

九、进阶配置

9.1 多工作区支持

{
  "mcpServers": {
    "workspace-a": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace/project-a"]
    },
    "workspace-b": {
      "command": "npx", 
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace/project-b"]
    }
  }
}

9.2 自定义 MCP 服务

# 安装自定义服务
npm install -g @modelcontextprotocol/server-sqlite

# 添加配置
{
  "mcpServers": {
    "sqlite": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sqlite", "database.db"]
    }
  }
}

十、总结

步骤操作关键点
1修改 Dockerfile全局安装 CLI + MCP 工具
2获取 TokenClaude/GitHub/Gemini/Codex
3创建配置文件JSON/TOML 格式
4配置挂载volumes 映射配置目录
5重建容器确保环境生效
6验证测试各工具可用性

核心原则：

  • 工具要全局安装，不要用 npx
  • Claude 配置用软链接固化
  • 配置文件通过 volumes 持久化

扩展阅读：

avatar
文章
阅读
粉丝