opencommit

环境要求

• Node.js 环境（用于 npm 全局安装，GitHub Action 示例中使用 node-version 16）
• npm 包管理器
• 已初始化的 Git 仓库，且有待提交的代码变更
• 一个受支持的 LLM 提供商 API Key（如 OpenAI，也可用 Anthropic、Gemini、DeepSeek、OpenRouter 等）
• 可选：本地 Ollama 或 llama.cpp，用于离线运行本地模型

安装与启动步骤

1. 1全局安装 OpenCommit

   通过 npm 把 opencommit 装到全局，装完后任意 Git 仓库里都能用 oco 命令。注意需要 npm 有全局写入权限。

   npm install -g opencommit

   复制

2. 2获取 API Key

   去 OpenAI 平台申请 API Key，并在账户里补充付款信息，否则接口无法调用。也可换成其他受支持的 LLM 提供商密钥。

3. 3写入 API Key 配置

   把密钥写进 OpenCommit 配置，密钥会保存在本机 ~/.opencommit 配置文件中，不会进仓库。

   oco config set OCO_API_KEY=<your_api_key>

   复制

4. 4生成提交信息

   先在仓库里暂存改动（可选，oco 会自动帮你 git add），然后执行 oco，约 1 秒生成提交信息并交互确认。

   git add <files...>
   oco

   复制

5. 5可选：改用本地 Ollama

   先装好并启动 ollama，首次拉取模型；然后在项目目录里把提供商切到 ollama 并指定模型，默认模型为 mistral。

   ollama run mistral
   oco config set OCO_AI_PROVIDER='ollama' OCO_MODEL='llama3:8b'

   复制

6. 6可选：接入 GitHub Action

   在仓库新建 .github/workflows/opencommit.yml，推送时自动改写新提交信息；需在仓库 Secrets 里配置 OCO_API_KEY。

关键配置

如何确认成功

在一个有待提交变更的仓库执行 oco，若能看到 AI 生成的提交信息并确认后成功提交，即表示配置生效。

常见问题

注意事项

• API Key 会以明文保存在本机 ~/.opencommit 配置文件中，注意不要把它提交到仓库。
• GitHub Action 会自动 rebase 改写推送的新提交，请在 branches-ignore 中排除 main、dev 等公共协作分支。
• 交互式 rebase 会改变提交 SHA，单独开发的分支没问题，多人协作时需谨慎。
• 使用 Ollama 时若服务跑在别的机器或 Docker 里，需要通过 OCO_API_URL 指向对应端点。