企业官网建设流程全解析

我真正把gemini当成命令行工具来使用，是源起于一次差点让我崩溃的体验：在网页端来回复制粘贴几十条提示词，然后手动把回答存成文件。两天之后我就意识到，照这样下去，我迟早要把时间全花在剪切板上。后来我把 gemini 的调用搬进终端，用一条命令完成提问、整理、保存，效率完全是另一个量级。这篇内容就是把我这段时间反复调整过的命令用法整理出来，给你一个可以直接照抄的版本。

Gemini 这个名字，现在基本等同于 Google 家的多模态大模型。普通用户日常接触最多的是网页版对话框，也就是在浏览器里登录、点击、输入、等回复。但如果你是个开发、运维、数据分析，或者经常写脚本处理文本的人，网页版的天花板很明显：没法批量处理，没法管道复用，没法把历史记录固化到项目里。把 gemini 的接口变成命令行调用，本质上是把“和模型对话”这件事嵌进你自己的自动化链路里。你会得到一个可以被脚本反复使用的 AI 工具，而不是每次都要手点的聊天框。

这篇内容覆盖了从零开始的 API 准备工作、最常用的几种命令操作、一个可复用的终端封装脚本，以及我实际踩过的报错和排查方法。适合对命令行有基本了解的人，也适合刚把 gemini 当成 API 接入项目的朋友。前半部分即使是新手也能跟着走，后半部分主要是写给打算长期用命令行折腾的人。

1. 为什么要折腾 Gemini 的命令行玩法

说实话，第一次听到“gemini 使用命令”这个说法的时候，很多人下意识会觉得：这不是一个网页聊天工具吗，怎么用命令？我还见过有人以为是在命令窗口输入什么神秘咒语就能唤出模型，其实没那么玄乎。这里的“命令”，本质上是向 Gemini API 发出 HTTP 请求，只是我们把请求的构造过程、返回结果的解析过程都固定成了一段可复用的脚本或函数，让它看起来像一条终端命令。

1.1 网页版和命令行谁更适合你

在动手之前，先想清楚一个问题：你到底需要在什么场景里使用 gemini。

我自己的选型原则很简单：一次性的、探索性的提问用网页；重复性的、要沉淀成流程的工作，用命令行。很多人一上来就想着装各种图形客户端，我的建议是先别折腾，先跑通命令行。跑通命令行之后，你对大模型 API 的请求结构会有更直观的理解，以后再去做网页应用、做小程序、做运维脚本，都会顺手很多。

1.2 你需要准备的命令行基础环境

基础环境不复杂，三样东西：

• 一个终端环境。Windows 上用 PowerShell 或者 Windows Terminal 都行，macOS 用系统自带的终端或者 iTerm2，Linux 更不用说了，随便一个 shell 都可以。
• curl，用来直接发 HTTP 请求。Windows 10 以上版本自带 curl，macOS 和 Linux 更是默认就有。
• jq，用来解析 JSON 返回结果。这个不是必须的，但强烈建议装，后面你会知道它能帮你省多少事。macOS 上可以用brew install jq，Ubuntu 上用apt install jq，Windows 可以下载可执行文件放到 PATH 里。

如果你只是想跟着看看效果，不需要安装什么 Gemini 桌面客户端，也不需要下载 Mac 版应用。Gemini 的命令行调用走的是 API，不是某个 GUI 程序，一条 curl 就是最小的完整用法。这一点想清楚，后面很多困惑都会消失。

2. Gemini API 接好，先跑通第一次对话

命令行调用 gemini，绕不开 API Key。这一步就像你进一家公司需要一个工牌，API Key 就是你的工牌。很多人把“登录网页版”和“取得 API Key”混在一起，其实是两件事。

2.1 在官方控制台拿 API Key，理解账号和密钥的区别

网页版登录的是对话界面，而 API Key 需要在专门的开发者控制台生成。进入 Google AI Studio 或者 Google Cloud 的相应页面，用你的账号登录之后，一般会看到一个“Get API key”按钮。点击生成之后，你会得到一串以AIza开头的字符串，这就是你的密钥。

生成之后记得立刻保存。很多平台只显示一次密钥，关掉弹窗之后就再也看不到完整内容了，只能重新生成。我一开始就是没保存，后来重新建了一次，浪费了几分钟，也提醒大家别踩这个坑。

拿到密钥之后，不要直接硬编码在命令里，也不要写进任何会被提交到版本库的脚本里。我的习惯是放在环境变量里。

export GEMINI_API_KEY="你的密钥"

macOS 和 Linux 可以直接写进~/.bashrc或~/.zshrc，Windows 可以在系统设置里加一个用户环境变量。这样做的好处是命令本身不泄露敏感信息，脚本也能到处复用。

有一点需要提前说明：不同时段可用模型名称会有变化。目前我常用的模型名是gemini-2.0-flash，它比早期版本更快，价格也友好，比较适合命令行场景。如果你拿到的是更新版本，建议去官方文档确认一下模型列表，别盲目照抄旧命令。

2.2 用 curl 发第一句“你好”

环境变量准备好之后，先来一次最小请求。命令行输入下面这串，把 API Key 传给请求头：

curl -s "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent" \ -H "Content-Type: application/json" \ -H "x-goog-api-key: $GEMINI_API_KEY" \ -d '{ "contents": [ { "parts": [ {"text": "用一句话解释什么是命令行工具"} ] } ] }'

如果你看到了一个 JSON 包着的中文回复，说明整个链路已经通了。这里要特别解释一下请求体的结构：contents是对话内容列表，parts是每一个对话片段里的具体部分，text就是你要发给模型的文本。Gemini API 的统一设计就是contents包裹parts，多轮对话无非是往contents里继续追加对象。

如果你用的是较新的 SDK，header 名称可能变化，但最原始的 HTTP 接口就是上面这个样子。理解了这个结构，后面无论用 Python、Node 还是 Go，都只是换了一层皮。

2.3 看懂返回 JSON，用 jq 精准提取

直接打印返回结果的话，那串 JSON 会把你眼睛看花。这时候jq登场。在上面命令后面接一个管道：

... | jq -r '.candidates[0].content.parts[0].text'

返回结构里，candidates是模型生成的候选结果数组，通常情况下你只用第 0 个。content.parts[0].text就是生成出来的正文内容。-r参数表示原样输出，不加引号。

还有一种更省事的做法：把 curl 命令封装成一个 shell 函数，以后只需要传一个问题就能拿结果。我在后文会给出完整脚本，这里先让你有“原来就这么简单”的感觉。跑通这一步之后，你已经从“只能点网页”进化到了“能用命令对话”的阶段。

3. 日常最常用的几类 Gemini 命令操作

跑通最小请求之后，接下来的问题就是怎么把它用得更顺。很多人以为命令行调大模型就是发一句话等一个回答，其实你还可以做多轮会话、让它看图、批量处理文档、精细控制输出风格。这几类操作我都拆开讲讲。

3.1 多轮会话与角色设定

如果你只是想聊天，把历史对话都带上就行。比如第一次用户问题是“你是谁”，模型回答完之后，第二次请求的contents里要包含用户消息、模型第一条回复、再追加新的用户消息。简单来说，把对话历史原样传回去。

命令行里手工维护历史并不方便，所以我一般不用 curl 做多轮，而是写脚本维护一个数组。Python 版本我会在下一章给出。用一个生活化的类比：多轮会话就像两个人聊天时必须记住前面说过什么，单次请求则恰好是鱼的记忆——说一句就忘一句。你要给模型记忆，就只能自己手动把历史拼进请求里。

角色设定的写法也比较直白。在请求体里增加一个system_instruction字段，就能让模型带上固定的人设或约束。比如：

"system_instruction": { "parts": [{"text": "你是一个严谨的中文技术编辑，回答简明扼要，不要客套"}] }

我在写文档摘要的时候特别依赖这个字段。不加系统指令，模型容易发散；加上一句“只返回结论和三个关键点”，输出质量会明显提升。

3.2 让模型理解图片与附件

Gemini 是多模态模型，命令行也可以让它“看图”。做法是先把图片转成 base64 编码，然后放进请求体的inline_data字段。这里给出一个 curl 的示例思路：

BASE64_IMAGE=$(base64 -w 0 /path/to/image.png) curl -s "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent" \ -H "Content-Type: application/json" \ -H "x-goog-api-key: $GEMINI_API_KEY" \ -d "{ \"contents\": [{ \"parts\": [ {\"text\": \"这张图里最显眼的是什么？\"}, {\"inline_data\": {\"mime_type\": \"image/png\", \"data\": \"$BASE64_IMAGE\"}} ] }] }" | jq -r '.candidates[0].content.parts[0].text'

注意 macOS 自带的base64命令没有-w 0参数，需要去掉换行符，或者用base64 | tr -d '\n'来做。这一点很容易忽略，我第一次在 macOS 上报 400 错误，排查了半天才发现是 base64 字符串里混进了换行符。

命令行处理图片的意义在于：你不用打开网页、拖拽图片、等待上传，直接在脚本里把图片路径换成变量，循环处理几百张截图都不是问题。比如批量读取目录下所有图片文件名，逐个让模型识别、输出描述、存成文本，这一套流程用网页版做会想撞墙。

3.3 批量处理文档并保存结果

命令行最大的优势是批量。我也是被这个场景打动的。以前写周报，要把十几个项目进展各写几句话，复制来粘贴去极其痛苦。现在是这样的一个循环：

for file in docs/*.txt; do echo "=== $file ===" cat "$file" | your_gemini_command "总结这段内容，50字以内" > "${file}.summary.md" done

不需要把模型输出一次次复制到本地，直接重定向到文件。再配合find、xargs、sed这些命令，可以做出很复杂的自动化流水线。譬如一个目录下所有 Markdown 文档都要生成摘要，一条find命令全部搞定，跑完之后目录里多出十几个.summary.md，这个效率提升是肉眼可见的。

可能有人会问：为什么不直接用网页版复制粘贴？原因是量大之后，手工操作会引入两个问题：一是人容易疲劳导致漏复制，二是格式杂乱要二次清理。命令行的确定性输出更适合写入文件系统、进入后续判断流程。

3.4 调参数：温度、输出长度、采样策略

刚开始用命令调用 gemini，你会发现同一个问题，回答冷不丁就超出了你想要的长度，或者风格不够稳。这时候可以调整三个常用参数：

• temperature：控制随机性。0 到 1 之间，值越低越稳定、越保守，越高越发散。写代码和做数据清洗我用 0.2，写文案我有时调到 0.8。
• maxOutputTokens：控制最多生成多少 token。默认值不设上限时，长文档可能有非常多内容。设置一个上限可以避免预算失控。
• topP：核采样参数，一般保持默认。多数情况下只调 temperature 就够了，不要同时猛调两个，容易顾此失彼。

我踩过的坑是：一次调试里同时把 temperature 调到 1.2，又把 topP 调到 0.9，结果输出虽然很有“创意”，但完全不守格式，连 JSON 都不再是合法的 JSON 了。后来我固定用低温度处理结构化任务，用中高温度处理创意写作任务。到你手头的场景，也可以按这个思路找到适合自己的默认值。

4. 实战：把 Gemini 封装成终端里的一个命令

跑通各种 API 调用之后，下一步自然就是封装。我希望在终端里输入一行gem，后面跟上问题，它就能把回答打印出来，让我不用每次看到那一大串 curl 拼接命令。

4.1 封装前的设计思路

封装的目标不是做一个功能天花乱坠的系统，而是解决三个日常痛点：

1. 不想每次记住那串超长的 curl 参数，最好一条简短命令直接提问。
2. 既支持参数提问，也支持管道输入。比如cat error.log | gem "帮我总结报错原因"这种用法。
3. 允许指定系统指令和模型名，方便不同场景切换。

我最终选型 Python，因为它在文本处理、字符串拼接和跨平台表现上都比较省心。Python 脚本最终配一个 shell alias，使用体验和原生命令差不多。

4.2 一个足够日常用的 Python 版本

这里给出我自己在用的简化版本，依赖只有一个官方 Python SDK。安装依赖：

pip install google-genai

然后新建一个gem.py：

#!/usr/bin/env python3 import argparse import os import sys from google import genai def main(): parser = argparse.ArgumentParser(description="gemini 命令行助手") parser.add_argument("--prompt", "-p", help="直接输入的提示词") parser.add_argument("--system", "-s", default="你是一个靠谱的助手，回答简洁准确。", help="系统设定") parser.add_argument("--model", "-m", default="gemini-2.0-flash", help="模型名称") parser.add_argument("--max-tokens", type=int, default=1024, help="最大输出 token 数") parser.add_argument("--temperature", type=float, default=0.4, help="采样温度") args = parser.parse_args() api_key = os.environ.get("GEMINI_API_KEY") if not api_key: sys.exit("请先设置环境变量 GEMINI_API_KEY") prompt_text = args.prompt if args.prompt else sys.stdin.read().strip() if not prompt_text: sys.exit("没有输入内容。请用 -p 传提示词，或者用管道传内容。") client = genai.Client(api_key=api_key) response = client.models.generate_content( model=args.model, contents=prompt_text, config={ "system_instruction": args.system, "max_output_tokens": args.max_tokens, "temperature": args.temperature, }, ) print(response.text) if __name__ == "__main__": main()

这个脚本虽然不复杂，但已经解决了大部分日常问题。直接输入python gem.py -p "介绍上海"，或者通过管道输入cat data.txt | python gem.py "提炼关键信息"都能工作。system参数默认值给了一个通用设定，不至于让模型过于放飞。

这里需要说明的是，不同版本的 SDK 在 config 字段命名上可能有细微差别，若报错就看一眼官方文档的迁移说明。我用的这个google-genai是最新一代客户端，比老的google-generativeai更简洁，建议新项目直接上。

4.3 用 shell alias 和函数简化输入

脚本文件写好后，把它放到/usr/local/bin/gem，或者用 alias 指向它：

alias gem="python3 /path/to/gem.py"

这样终端里就多了一条名为gem的命令。我实测过很多次，这种手法比真正的“安装一个 gemini 客户端”更透明，出了问题也知道去哪查。我也习惯加上--system参数切换不同场景。比如代码审查时，我常用这个指令：

git diff | gem --system "你是资深代码审查员，指出潜在 bug、安全隐患和可读性问题" "帮我 review 这段改动"

你可以把不同场景的 system prompt 固化在配置文件里，然后给每个场景做一个独立 alias，例如alias gem-review="gem --system '你是资深代码审查员'"，使用起来几乎不用思考。

4.4 扩展：把命令接进任务编排

单一命令已经很好用，但真正让人舒服的是把它和其他命令行工具串起来。这一节就说几个我目前仍在用的组合方式。

Git 提交信息生成：

git diff --stat | tail -5 && git diff | gem -s "根据diff写3条提交信息候选，每条不超过15字" > commit_msg.txt

定时摘要任务，可以用 cron 或系统计划任务实现。比如每天晚上九点自动跑一个脚本，把当天新生成的文档目录清单发给 gemini，让它生成明日计划建议并写入指定文件。整个过程无人值守，第二天打开文件就看到结果。

日志快速分析：

tail -200 app.log | gem -s "你是运维专家，只提取异常和根因" "日志里有什么值得关注的问题？"

这个用法很适合值班场景。以前人工看日志要眯着眼睛找关键字，现在把日志丢给模型，等于多了一个帮你先过一遍的同事。

5. 命令使用中的常见报错与排查方法

命令行工具的好处是错误信息直接打在终端里，但坏处是错误信息不一定好看。下面这些报错我都亲自撞过，处理办法也都验证过。

5.1 鉴权失败：401 / 403 / invalid_api_key

这类报错的回复一般类似API key not valid. Please pass a valid API key.。排查步骤依次是：

1. 确认环境变量是否正确加载：终端里执行echo $GEMINI_API_KEY，如果输出为空说明这个 shell 会话里还没 export，需要重新加载配置文件。
2. 确认密钥是否复制完整：AIza后面一串字符，漏一位都不行。
3. 确认密钥是否仍然有效：去控制台看一眼密钥状态，如果被删了或者被禁用了，重新生成。

我遇到过最隐蔽的情况是：.bashrc里 export 了一句，但当前窗口没有source ~/.bashrc，于是死活 403。这个问题在换新终端窗口时尤其常见，值得记住。

5.2 返回 400：请求结构写错了

400 错误大部分是 JSON 或者字段名的问题。我看过很多新手把contents拼成了content，或者把parts拼成了part。这类问题没法靠后端容错，必须严格照官方文档来。

另外，base64 数据里的换行符也会导致 400，尤其是 macOS 上用base64命令时。处理办法是生产 base64 字符串后去除所有换行：

BASE64_IMAGE=$(base64 -w 0 image.png)

如果系统 base64 不支持-w，就用base64 image.png | tr -d '\n'。

5.3 中文显示乱码或回答被截断

中文乱码一般不是模型的问题，而是终端编码的问题。Windows PowerShell 里默认编码如果不是 UTF-8，很容易看到乱码。在 PowerShell 里先执行：

[Console]::OutputEncoding = [System.Text.Encoding]::UTF8

curl 命令返回的 JSON 也可能因为转义问题导致中文变样，建议优先用 jq 或者 Python 直接解析。

回答被截断则跟maxOutputTokens直接相关。默认值如果在某些接口下偏小，长回答会在中途戛然而止。在命令里显式调大，比如--max-tokens 4096，就很少出现这种问题。输出到文件后检查最后一条是否为完整结束，也比盯着屏幕更可靠。

5.4 上下文超过模型限制

多轮对话或者传入超大文档时报错，常见提示是prompt is too long。本质原因是输入 token 数超过了模型的上下文窗口。

解决办法有三个方向：

1. 对输入做裁剪：日志只取最后 200 行，文档只取关键片段。
2. 分段处理再合并结果：把一个长文档拆成若干段，逐段让模型总结，最后再汇总。
3. 换成上下文窗口更大的模型，但这个选择会带来成本和延迟变化，需要权衡。

我处理长文时常用一个取巧方案：先用head -100取前 100 行，再tail -100取后 100 行，只把这两段丢给模型。对于大多数文本类任务，这个简单策略能覆盖至少 90% 的需求。

5.5 网络超时和临时失败

命令行调用如果网络不稳定，curl 会偶尔报超时。这类问题用增加超时和自动重试来缓解。

curl --retry 3 --retry-delay 2 --max-time 60 ...

在 Python SDK 上也可以配置超时参数。如果遇到 429 之类的限流错误，思路是退避重试，一般是等待几秒再发，别死磕同一个请求刷个不停。排错顺序上，先确认本机到官方 API 的网络连通性，再考虑是不是 API Key 或者请求包的问题。

有一个容易忽略的点：系统时间如果偏差太大，也会导致鉴权异常。这是个冷门坑，我曾在配置较乱的开发机上遇到过，校时之后请求就正常了。如果所有其他排查都无效，不妨检查一下本机时间。

6. 沉淀下来后的个人用法与心得

把 gemini 的命令行用法跑顺之后，我发现它真正改变的不是某一次任务的效率，而是我处理信息的姿势。下面这些方法不保证适合所有人，但都是我用顺手之后觉得值得记录的。

6.1 在代码评审里搭一个会看 diff 的助手

代码审查是我用得最频繁的场景之一。刚使用命令行时，我把git diff丢给模型，它只能泛泛而谈。后来我加了约束：不聊风格问题，只找逻辑风险；每条评论必须指出具体行号。这个效果立刻就不一样了。

这个用法给我的启发是：prompt 越具体、越有约束，模型回应越接近你真正想要的。建议你在自己的项目里也建一条“审查指令”模板，而不是临时写一段话丢给它。

6.2 日志和文本批处理的固定套路

我现在处理日志，不管是在服务器上还是本地文件，基本流程早就固定了：先tail取出最近一段，再丢给 gemini 摘要异常。如果是大量文本要做清洗、格式转换或分类，管道里先把非关键部分过滤掉，再把核心内容交给模型。

核心原则是先缩小输入，再调用模型。这样既能省 token，也能明显降低跑错或乱答的概率。命令行调大模型的正确姿势永远不是把什么都往里塞，而是把最有可能含答案的部分选出来。

6.3 把回答直接喂给编辑器

这一条对写文档特别有用。我用 Vim 比较多，平时会在 Vim 里通过:!执行外部命令，把 gemini 的输出插到当前文档中，或者写入临时文件再读取。这个方法把“模型生成内容”变成了文档编辑的一部分，跟复制粘贴两个窗口相比，少了很多来来回回的操作。

在其他编辑器里同理。只要编辑器能执行外部命令，或者你愿意用剪贴板中转，这条思路都是成立的。本质上，gemini 命令生成了标准输出，而任何能接受标准输出的编辑器都能接入。

6.4 给新手的五个使用建议

1. 先跑通一条 curl，再看 SDK 文档。直接上 SDK 很容易遇到背后的抽象问题，搞不懂根因。
2. 把 API Key 放进环境变量，已经说过第三遍，但还是最重要的一条。
3. 遇到报错先看消息提示，再翻文档。Google 风格的报错通常会告诉你哪个字段有问题。
4. 一开始不要追求一步到位的完整封装，先攒几个固定命令，摸索出自己的使用方式。
5. 批量场景务必先小样本验证，不要一上来就处理全部文件，避免错误状态被复制几百份。

最后说一点个人体会。很多人看到命令行调 AI，第一反应是觉得多此一举，网页聊聊天不也挺好。可我每次打开终端，面对十几个文件、几十行日志、一堆 git diff 的时候，都会感谢当初花两个晚上把这几套命令调通。它没有吞掉我的工作流程，而是自然地嵌进了我原本就在用的那些工具里。如果这篇内容能让你把 gemini 的调用从“网页版”升级到“命令行版”，并且避开我踩过的那些坑，那我觉得这通折腾非常值。