Gemini CLI — macOS 安装配置

本指南帮助你在 macOS 上安装并配置 Google Gemini CLI，接入 TinyPx API 服务。

前置要求

• macOS 10.15 (Catalina) 或更高版本
• Node.js 20.0 或更高版本
• npm 包管理器

步骤 1：安装 Node.js

方法一：Homebrew（推荐）

brew install node

方法二：nvm

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 重新加载配置
source ~/.zshrc   # 如果使用 zsh
source ~/.bashrc  # 如果使用 bash

# 安装 Node.js LTS
nvm install --lts
nvm use --lts

方法三：官方安装包

1. 访问 nodejs.org
2. 下载 macOS Installer（.pkg）
3. 运行安装程序，按默认设置完成安装

验证安装

node --version
npm --version

步骤 2：全局安装 Gemini CLI

npm install -g @google/gemini-cli

验证安装：

gemini --version

步骤 3：配置 Gemini CLI

重要提示

请把下方的 GEMINI_API_KEY 替换为你在 TinyPx API 控制台 生成的 Gemini CLI 专用 API 密钥。

3.1 创建 .gemini 文件夹

mkdir -p ~/.gemini
cd ~/.gemini

配置位置：~/.gemini/

3.2 创建 .env 文件

cat > ~/.gemini/.env << 'EOF'
GOOGLE_GEMINI_BASE_URL=https://ai.tinypx.cn
GEMINI_API_KEY=粘贴为 Gemini CLI 专用分组令牌 key
GEMINI_MODEL=填写该 Gemini CLI 分组支持的模型名
EOF

或手动创建 .env 文件：

GOOGLE_GEMINI_BASE_URL=https://ai.tinypx.cn
GEMINI_API_KEY=粘贴为 Gemini CLI 专用分组令牌 key
GEMINI_MODEL=填写该 Gemini CLI 分组支持的模型名

可用模型

具体可用模型请到 模型广场 查阅该 Gemini CLI 分组支持的 model 及价格。

3.3 创建 settings.json 文件

cat > ~/.gemini/settings.json << 'EOF'
{
  "ide": {
    "enabled": true
  },
  "security": {
    "auth": {
      "selectedType": "gemini-api-key"
    }
  }
}
EOF

注意

配置改动需要重启 Gemini CLI 才生效。

建议限制密钥文件权限：

chmod 600 ~/.gemini/.env

步骤 4：启动 Gemini CLI

gemini

开始使用 Gemini CLI：

• 超大上下文窗口：1M tokens
• Agent Mode 自动规划任务
• Google Search 实时联网

常用命令

# 启动交互式会话
gemini

# 非交互式提示
gemini -p "创建一个 React 组件"

# 分析代码文件
gemini -p "分析 file.js 并指出可以改进的地方"

# 查看帮助
gemini --help

故障排除

命令未找到

npm config get prefix
echo $PATH

添加到 PATH：

# Zsh（macOS 默认）
echo 'export PATH="$PATH:$(npm config get prefix)/bin"' >> ~/.zshrc
source ~/.zshrc

# Bash
echo 'export PATH="$PATH:$(npm config get prefix)/bin"' >> ~/.bashrc
source ~/.bashrc

API 连接失败

# 检查密钥配置
cat ~/.gemini/.env

# 确认设置文件
cat ~/.gemini/settings.json

# 测试端点
curl -I https://ai.tinypx.cn

权限错误

改用用户级 npm 目录：

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

Apple Silicon（M 系列芯片）兼容性

# 使用 Rosetta
arch -x86_64 npm install -g @google/gemini-cli

# 或指定原生架构
npm install -g @google/gemini-cli --target_arch=arm64

下一步

• Windows 安装指南
• Linux 安装指南
• Claude Code 配置
• Codex 配置

获取 API 密钥

访问 TinyPx API 控制台 获取你的 Gemini CLI 专用令牌。