「CC 被 A 社限制使用，Codex 逐渐发力，代码之巅，新王加冕」

最近 Anthropic 小动作挺多，比如说：

1. 2.1.15 版本开始逐渐弃用 npm 的安装方式
2. claude code 一些暗配置在云上，方便 Anthropic 云控
3. Anthropic 明牌抵制大陆公司，大陆 IP 使用
4. 接下来，好像还有一些小动作，这些信号告诉我们，需要备用方案

# Codex 示例配置（config.toml）V1.0 
# 作者：大帅笔 
# https://linux.do/u/dwifbytslqh/summary
################################################################################
# 核心模型选择
################################################################################

# Codex 使用的主模型。默认：所有平台均为 "gpt-5.2-codex"。
# 支持 gpt-5.2-codex, gpt-5.2, o1-pro-codex 等
model = "gpt-5.2-codex"

# /review 功能（代码审查）使用的模型。默认："gpt-5.2-codex"。
# 可设置为不同的模型以优化代码审查效果
review_model = "gpt-5.2-codex"

# 从 [model_providers] 中选择的提供方 id。默认："openai"。
# 可选值：openai, azure, ollama 等，需在 [model_providers] 部分定义
model_provider = "openai"

# 用于 --oss 会话的默认开源提供方。未设置时，Codex 会提示选择。默认：未设置。
# 设置为 ollama 等支持开源模型的提供方
# oss_provider = "ollama"

# 可选的手动模型元数据。未设置时，Codex 会根据 model 自动检测。
# 取消注释以强制指定这些值。
# 模型的上下文窗口大小（token 数），影响单次请求可处理的最大代码量
# model_context_window = 128000       # token 数；默认：按模型自动决定

# 自动触发历史压缩的 token 阈值，0 表示使用模型默认值
# model_auto_compact_token_limit = 0  # token 数；未设置时使用模型默认值

# 每个工具输出存储的最大 token 数，防止工具输出占用过多上下文
# tool_output_token_limit = 10000     # 每个工具输出存储的 token 数；对 gpt-5.2-codex 默认是 10000

################################################################################
# 推理与详细度（支持 Responses API 的模型）
################################################################################

# 推理强度：minimal | low | medium | high | xhigh（默认：medium；在 gpt-5.2-codex 与 gpt-5.2 上为 xhigh）
# 更高的推理强度会让模型思考更充分，但响应时间更长
model_reasoning_effort = "medium"

# 推理摘要：auto | concise | detailed | none（默认：auto）
# 控制是否显示模型的推理过程摘要
model_reasoning_summary = "auto"

# GPT-5 系列（Responses API）的文本输出详细度：low | medium | high（默认：medium）
# 影响模型回复的详细程度
model_verbosity = "mediummedium"
# model_reasoning_summary = "auto"
# model_verbosity = "medium"
# chatgpt_base_url = "https://chatgpt.com/backend-api/ "
# experimental_compact_prompt_file = "./compact_prompt.txt"
# include_apply_patch_tool = false
# experimental_use_unified_exec_tool = false
# experimental_use_freeform_apply_patch = false
# tools_web_search = false
# features = { unified_exec = false }

################################################################################
# Projects（信任级别）
################################################################################

# 将特定 worktree 标记为可信或不可信。
# 为不同项目设置不同的信任级别
[projects]

# 项目路径设置示例
# [projects."/absolute/path/to/project"]
# trust_level = "trusted"  # 或 "untrusted"

################################################################################
# OpenTelemetry（OTEL）- 默认禁用
################################################################################

# 可观测性配置，用于监控和调试
[otel]

# 在日志中包含用户提示文本。默认：false（出于隐私考虑）
log_user_prompt = false

# 应用于遥测数据的环境标签。默认："dev"
environment = "dev"

# 导出器：none（默认） | otlp-http | otlp-grpc
# 设置为 none 则禁用遥测导出
exporter = "none"

# Trace 导出器：none（默认） | otlp-http | otlp-grpc
trace_exporter = "none"

# 示例：OTLP/HTTP 导出器配置
# [otel.exporter."otlp-http"]
# endpoint = "https://otel.example.com/v1/logs "  # OTLP 接收端点
# protocol = "binary"                         # "binary" | "json"

# [otel.exporter."otlp-http".headers]
# "x-otlp-api-key" = "${OTLP_TOKEN}"  # 从环境变量读取 API 密钥

# 示例：OTLP/gRPC 导出器配置
# [otel.exporter."otlp-grpc"]
# endpoint = "https://otel.example.com:4317 "
# headers = { "x-otlp-meta" = "abc123" }

# 示例：带双向 TLS 的 OTLP 导出器
# [otel.exporter."otlp-http"]
# endpoint = "https://otel.example.com/v1/logs "
# protocol = "binary"

# [otel.exporter."otlp-http".headers]
# "x-otlp-api-key" = "${OTLP_TOKEN}"

# [otel.exporter."otlp-http".tls]
# ca-certificate = "certs/otel-ca.pem"  # CA 证书路径
# client-certificate = "/etc/codex/certs/client.pem"  # 客户端证书
# client-private-key = "/etc/codex/certs/client-key.pem"  # 客户端私钥

config.toml.txt

MCP 推荐：

windows 版：

[mcp_servers.chrome-devtools] command = "cmd" args = [
  "/c",
  "npx",
  "-y",
  "chrome-devtools-mcp@latest",
]
env = { SystemRoot="C:\\Windows", PROGRAMFILES="C:\\Program Files" }
startup_timeout_ms = 60_000 [mcp_servers.context7] command = "cmd" args = [
"/c",
"npx",
"-y",
"@upstash/context7-mcp",
"--api-key",
"YOUR_API_KEY"
]
env = { SystemRoot="C:\Windows" }
startup_timeout_ms = 20_000 [mcp_servers.replicate] command = "cmd" args = [
  "/c",
  "npx",
  "-y",
  "replicate-flux-mcp"
]
env = { SystemRoot="C:\\Windows", PROGRAMFILES="C:\\Program Files", REPLICATE_API_TOKEN="r8_MPwJVCYxBSvrYNSETThDE69JQwAAk9SC3r7XSW" }
startup_timeout_ms = 60_000 [mcp_servers.github] command = "cmd" args = [
  "/c",
  "npx",
  "-y",
  "mcp-remote@latest",
  "https://api.githubcopilot.com/mcp/",
  "--header",
  "Authorization: Bearer xx_Axxx7ICfgT0Vyyd6"
]
env = { SystemRoot="C:\\Windows", PROGRAMFILES="C:\\Program Files" }
startup_timeout_ms = 60_000`

MacOS 版：

[mcp_servers.chrome-devtools]
command = "npx"
args = [
  "-y",
  "chrome-devtools-mcp@latest"
]


[mcp_servers.context7]
args = ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"]
command = "npx"


[mcp_servers.replicate]
command = "npx"
args = [
  "-y",
  "replicate-flux-mcp"
]
env = {"REPLICATE_API_TOKEN="r8_MPwJVCYxbSvrYNSETHDE69JQwAAk9sC3r7XSW"}


[mcp_servers.github]
command = "npx"
args = [
    "-y",
    "mcp-remote@latest",
    "https://api.githubcopilot.com/mcp/",
    "--header",
    "Authorization: Bearer sssssHU5HQZGK4ssgT0Vyyd6"
]


[mcp_servers.sequential-thinking]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-sequential-thinking"]

[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]

[mcp_servers.mcp-server-time]
command = "uvx"
args = ["mcp-server-time", "--local-timezone=Asia/Shanghai"]

[mcp_servers.mcp-shrimp-task-manager]
command = "npx"
args = ["-y", "mcp-shrimp-task-manager"]
env = { DATA_DIR = "/Users/lostsheep/tools/mcp-shrimp-task-manager/data", TEMPLATES_USE = "zh", ENABLE_GUI = "false" }

[mcp_servers.mcp-deepwiki]
command = "npx"
args = ["-y", "mcp-deepwiki@latest"]

[mcp_servers.desktop-commander]
command = "npx"
args = ["-y", "@wonderwhy-er/desktop-commander"]
# --- End MCP servers ---

Skills

---
name: openspec
description: OpenSpec 中文版规范助手 - 规范驱动的 AI 编程开发，帮助初始化、创建提案、编写规格、校验格式并归档变更。触发条件： 当用户提及 openspec、规范文档、需求管理、变更提案、spec-driven development 等关键词时主动调用。
trigger: 当用户提及 openspec、规范文档、需求管理、变更提案、spec-driven development 等关键词时主动调用
---

# OpenSpec 中文版规范助手

OpenSpec 是一个 CLI 工具，通过**规范驱动的开发流程**帮助开发者与 AI 编码助手建立明确的需求共识。核心理念是：**在编写代码前，先将需求文档化并达成一致**，从而消除 AI 工具仅依赖对话历史产生的不可预测输出。

## 什么是 OpenSpec

### 核心价值

- **准确性**：需求明确后大幅减少返工，避免 AI 理解偏差
- **可追溯性**：每个技术决策都有完整的文档记录
- **文档化**：自动生成的规范与代码保持同步，形成活文档
- **团队友好**：清晰的提案便于多人协作和 Code Review

### 适用场景

✅ **最适合**：

- 改进现有项目（1→n 开发，棕地项目）
- 需要高质量实现的关键功能
- 团队协作开发
- 使用 Claude Code、Cursor、Cline 等 AI 工具
- 需要长期维护的项目

❌ **不适合**：

- 快速原型验证（0→1 探索阶段）
- 一次性小脚本
- 需求极度不明确的创新性探索

### 实践价值

前期多花 10-15 分钟与 AI 澄清需求、编写规范，能节省数小时的返工时间。规范文档会随着项目演进不断积累，最终形成完整的系统文档。

## 双文件夹模型

OpenSpec 使用独特的**双文件夹模型**，将"事实"与"提案"分离：

```plain
openspec/
├── specs/          # 📚 事实：已实施并归档的规范（source-of-truth）
│   ├── auth.md
│   ├── api.md
│   └── database.md
└── changes/        # 💡 提案：待实施的变更（明确的差异管理）
    ├── add-oauth-login/
    │   ├── proposal.md
    │   ├── tasks.md
    │   └── specs/
    │       └── auth-delta.md
    └── optimize-api-cache/
        ├── proposal.md
        └── specs/
            └── api-delta.md
```

**设计理念**：

- `specs/` 是系统的当前状态
- `changes/` 是即将到来的变化
- 这种分离让"差异明确且可管理"，特别适合修改现有系统

## 环境与安装

### 基本要求

- **Node.js** >= 20.19.0（Node 22 也兼容）
- **无需 API 密钥**：完全本地执行，与现有开发工具集成

### 安装方式

**全局安装（推荐）**：

```bash
npm install -g @org-hex/openspec-chinese@latest
# 或使用 pnpm
pnpm install -g @org-hex/openspec-chinese@latest
```

**临时使用**（不安装）：

```bash
pnpm dlx @org-hex/openspec-chinese init
pnpm dlx @org-hex/openspec-chinese proposal "功能描述"
```

**验证安装**：

```bash
openspec-chinese --version
openspec-chinese --help
```

### 支持的 AI 工具

OpenSpec 支持 **20+ AI 编程助手**，包括：

- **原生斜杠命令**：Claude Code, Cursor, CodeBuddy, Cline 等
- **AGENTS.md 回退**：所有支持自定义指令的工具（通用兼容）

无需额外配置，安装后即可在所有支持的工具中使用。

## 项目初始化

### 初始化结构

```bash
# 在全新项目中初始化
openspec-chinese init

# 在现有 OpenSpec 项目中切换到中文版
openspec-chinese update
```

生成的完整结构：

```plain
openspec/
├── project.md      # 项目上下文（技术栈、架构、团队约定）
├── AGENTS.md       # AI 助手通用指令（20+ 工具兼容）
├── specs/          # 现行规范库（已归档的事实）
├── changes/        # 变更提案目录
└── templates/      # 自定义模板（可选）
```

**重要**：初始化后如果 IDE 里斜杠命令未出现，请重启 IDE/AI 工具。

### 补全 project.md

生成 `project.md` 后，应立即向 AI 提出：

```markdown
请阅读 openspec/project.md 并帮助我填写：

1. 项目的核心技术栈
2. 架构设计约定
3. 编码规范和最佳实践
4. 团队协作流程
```

完善的 `project.md` 能让 AI 助手更好地理解项目上下文，生成更符合实际的规范文档。

## 五阶段完整工作流程

### 阶段 1：起草提案（Draft Proposal）

**目标**：创建变更文件夹，初步定义需求

```bash
# 命令行方式
openspec-chinese proposal "添加 OAuth 登录功能"

# AI 工具斜杠命令
/openspec-proposal
```

**输出**：

```plain
openspec/changes/add-oauth-login/
├── proposal.md     # AI 生成的初步提案
├── tasks.md        # 任务分解清单
└── specs/          # 增量规范（空）
```

**交互要点**：

- AI 会提出澄清问题（例如："使用哪些 OAuth 提供商？"）
- 回答问题后，AI 生成详细的 `proposal.md` 和 `tasks.md`

### 阶段 2：审查对齐（Review & Align）

**目标**：人和 AI 共同审查，反复迭代直到需求明确

```bash
# 查看提案详情
openspec-chinese show add-oauth-login

# 在 AI 工具中交互
"请根据我的反馈修改 proposal.md：
1. 只支持 GitHub 和 Google OAuth
2. 需要处理现有用户的账号合并逻辑
3. 增加 OAuth 失败时的降级方案"
```

**迭代过程**：

1. 审查 `proposal.md` 的 Why/What/Impact
2. 检查 `tasks.md` 的任务拆解是否合理
3. 提出修改建议，让 AI 更新文档
4. 重复直到完全对齐

**关键**：这个阶段多花时间，后续实施会快很多。

### 阶段 3：编写规格（Write Specs）

**目标**：在 `specs/` 目录下编写符合格式的增量规范

```bash
# AI 工具中请求
"请为 add-oauth-login 变更编写规格文档，放在 specs/ 目录"
```

**规范格式**（详见下文"规格文档格式要求"）：

```markdown
## ADDED Requirements

### Requirement: OAuth 登录支持

系统 MUST 支持通过 GitHub 和 Google 进行 OAuth 登录。

#### Scenario: GitHub OAuth 登录成功

- **WHEN** 用户点击"使用 GitHub 登录"按钮
- **THEN** 系统跳转到 GitHub OAuth 授权页面
- **AND** 授权成功后返回并创建会话
```

### 阶段 4：校验与实施（Validate & Implement）

**校验格式**：

```bash
# 严格格式校验
openspec-chinese validate add-oauth-login --strict

# 中文格式专项校验（需配置）
npm run validate:chinese
```

**实施开发**：

```bash
# AI 工具中参考规范实施
"请参考 openspec/changes/add-oauth-login/specs/ 中的规范，
按照 tasks.md 的任务清单逐步实施功能"
```

**任务追踪**：

- 在 `tasks.md` 中勾选已完成的任务
- AI 会自动参考规范，减少理解偏差

### 阶段 5：归档与文档化（Archive & Document）

**目标**：将完成的变更合并到主规范库

```bash
# 查看所有变更
openspec-chinese list

# 归档已完成的变更
openspec-chinese archive add-oauth-login --yes
```

**效果**：

- `changes/add-oauth-login/` 的规范合并到 `specs/`
- 变更记录自动保存
- 形成活文档，与代码同步

### 流程图总览

```mermaid
flowchart TD
  A[1. 起草提案<br/>AI 澄清问题] --> B[2. 审查对齐<br/>迭代完善需求]
  B --> C[3. 编写规格<br/>Delta + Scenarios]
  C --> D[4. 校验格式<br/>validate --strict]
  D --> E{格式正确?}
  E -- 否 --> C
  E -- 是 --> F[5. 实施开发<br/>按规范编码]
  F --> G[6. 归档文档<br/>archive --yes]
  G --> H[规范库更新<br/>活文档形成]
```

## 规格文档格式要求

OpenSpec 使用**严格的格式规范**，确保 AI 和人都能准确理解需求。

### 核心原则

1. **Delta 分区**：使用英文标题标识变更类型
2. **强制关键词**：需求必须包含 MUST/SHALL/SHOULD
3. **Gherkin 场景**：使用英文关键字描述验收标准
4. **中英混合**：结构英文，描述中文

### 1. Delta 分区（必填）

**三种变更类型**：

```markdown
## ADDED Requirements

# 新增的能力

## MODIFIED Requirements

# 修改现有行为

## REMOVED Requirements

# 废弃的功能（需说明原因和迁移路径）
```

### 2. Requirement 语句规范

**格式**：

```markdown
### Requirement: [需求名称]

系统 [MUST/SHALL/SHOULD] [能力描述]。
```

**强制关键词**：

- **MUST** / **SHALL**：强制要求，不可妥协
- **SHOULD**：建议要求，可协商
- **MAY**：可选要求

**示例**：

```markdown
### Requirement: 用户搜索功能

系统 MUST 提供用户搜索功能，支持按用户名、邮箱、手机号进行模糊查询。

系统 SHOULD 在搜索结果中高亮匹配的关键词。
```

### 3. Scenario 场景描述（验收标准）

**格式**：

```markdown
#### Scenario: [场景名称]

- **WHEN** [前置条件]
- **THEN** [预期结果]
- **AND** [额外条件/结果]
```

**要求**：

- 每个 Requirement 至少有一个 Scenario
- 使用**英文 Gherkin 关键字**（WHEN/THEN/AND/GIVEN）
- 描述内容可以是中文

**示例**：

```markdown
#### Scenario: 按邮箱搜索用户

- **WHEN** 用户在搜索框输入 "test@example.com"
- **THEN** 系统返回邮箱包含该字符串的用户列表
- **AND** 列表按相关度排序
- **AND** 邮箱中的匹配部分高亮显示

#### Scenario: 搜索无结果

- **WHEN** 用户输入不存在的邮箱
- **THEN** 系统显示"未找到匹配用户"
- **AND** 提示用户检查输入或尝试其他搜索条件
```

### 4. 删除需求的特殊要求

删除需求时**必须**提供 Reason 和 Migration：

```markdown
## REMOVED Requirements

### Requirement: 用户密码明文存储

- **Reason**: 严重的安全隐患，违反 OWASP 安全规范
- **Migration**:
  1. 所有密码已迁移到 bcrypt 加密存储
  2. 用户首次登录时会自动升级密码加密方式
  3. 详细迁移指南：`docs/password-migration.md`
```

### 5. 修改需求的说明

修改现有功能时应说明变化：

```markdown
## MODIFIED Requirements

### Requirement: 用户列表分页

- **变化说明**: 将每页默认显示数量从 20 条调整为 50 条
- **原因**: 用户反馈每页 20 条过少，频繁翻页影响体验
- **影响范围**:
  - 前端分页组件
  - 后端 API 默认参数
  - 性能测试基准需重新评估

#### Scenario: 默认分页数量

- **WHEN** 用户访问用户列表页面
- **THEN** 系统默认每页显示 50 条记录
- **AND** 用户可以在设置中自定义每页条数（10/20/50/100）
```

### 6. 完整示例模板

```markdown
## ADDED Requirements

### Requirement: 用户数据导出功能

系统 MUST 提供用户数据导出功能，支持 CSV 和 JSON 两种格式。

#### Scenario: 导出为 CSV 格式

- **WHEN** 管理员点击"导出为 CSV"按钮
- **THEN** 系统生成包含所有用户数据的 CSV 文件
- **AND** 文件包含字段：用户名、邮箱、注册时间、最后登录时间、状态
- **AND** 文件名格式为 `users_export_YYYYMMDD_HHmmss.csv`

#### Scenario: 导出权限检查

- **WHEN** 非管理员用户尝试导出
- **THEN** 系统返回 403 Forbidden 错误
- **AND** 前端显示"权限不足"提示

#### Scenario: 大数据量导出

- **GIVEN** 系统有超过 10000 条用户记录
- **WHEN** 管理员点击导出
- **THEN** 系统显示"正在生成导出文件"进度提示
- **AND** 导出任务在后台异步执行
- **AND** 完成后通过邮件发送下载链接

## MODIFIED Requirements

### Requirement: 用户列表查询性能

- **变化说明**: 为用户表添加邮箱和手机号索引
- **原因**: 当前搜索性能在 10 万用户以上明显下降
- **预期效果**: 搜索响应时间从 2-3 秒降低到 < 500ms

## REMOVED Requirements

### Requirement: 用户密码明文存储

- **Reason**: 严重安全隐患，必须移除
- **Migration**:
  1. 所有密码已迁移到 bcrypt 加密（cost=10）
  2. 用户下次登录时自动完成迁移
  3. 详细文档：`docs/security/password-migration.md`
```

## 常用命令速查

### 项目管理

```bash
# 初始化全新项目
openspec-chinese init

# 更新/切换到中文版
openspec-chinese update

# 查看版本
openspec-chinese --version
```

### 变更管理

```bash
# 创建新提案
openspec-chinese proposal "功能描述"

# 查看所有变更
openspec-chinese list

# 查看特定变更详情
openspec-chinese show <change-name>

# 校验格式（严格模式）
openspec-chinese validate <change-name> --strict

# 归档已完成的变更
openspec-chinese archive <change-name> --yes
```

### AI 工具斜杠命令

在支持的 AI 工具（Claude Code, Cursor 等）中：

```bash
/openspec-proposal          # 创建新提案
/openspec-validate          # 校验当前变更
/openspec-archive           # 归档变更
```

## 自定义模板

### 创建模板

在 `openspec/templates/` 目录下创建自定义模板：

```bash
# 创建功能规格模板
openspec/templates/feature-spec.md

# 创建 API 规格模板
openspec/templates/api-spec.md

# 创建数据库变更模板
openspec/templates/db-migration-spec.md
```

### 模板示例

```markdown
<!-- openspec/templates/feature-spec.md -->

## ADDED Requirements

### Requirement: [功能名称]

系统 MUST [功能描述]。

#### Scenario: [主要场景]

- **WHEN** [前置条件]
- **THEN** [预期结果]
- **AND** [额外条件]

#### Scenario: [错误场景]

- **WHEN** [异常情况]
- **THEN** [错误处理]
- **AND** [用户提示]

## MODIFIED Requirements

（如有修改现有功能，在此说明）

## REMOVED Requirements

（如有废弃功能，在此说明原因和迁移路径）
```

### 使用模板

```bash
# 创建新变更时，从模板复制
cp openspec/templates/feature-spec.md openspec/changes/new-feature/specs/feature.md

# 然后填充具体内容
```

## 最佳实践

### 1. 提案阶段多花时间

- ✅ 与 AI 充分沟通，澄清所有疑问
- ✅ 详细拆解任务到可执行的粒度
- ✅ 确保 proposal.md 中的 Why/What/Impact 清晰
- ❌ 不要急于开始编码，需求不明会导致大量返工

### 2. 规格要具体可验证

- ✅ 每个需求至少有 1-2 个 Scenario
- ✅ Scenario 要具体，可直接转化为测试用例
- ✅ 包含正常流程和异常流程
- ❌ 避免模糊描述，如"系统应该快速响应"

### 3. 利用 validate 命令

```bash
# 每次编辑规格后立即校验
openspec-chinese validate <change> --strict

# 配置 Git pre-commit hook
npm run validate:chinese
```

### 4. 保持规范与代码同步

- ✅ 代码实现后，确保规范准确反映最终结果
- ✅ 如有偏差，更新规范或代码使其一致
- ✅ 归档前再次审查规范的准确性

### 5. 利用 project.md

```markdown
<!-- openspec/project.md -->

# 项目上下文

## 技术栈

- 前端: React 18 + TypeScript
- 后端: Node.js + Express
- 数据库: PostgreSQL 14

## 架构约定

- RESTful API 设计
- JWT 认证
- 统一错误处理中间件

## 编码规范

- ESLint + Prettier
- 函数式组件优先
- 使用 React Query 管理服务端状态
```

完善的 `project.md` 能让 AI 生成更符合项目规范的代码。

### 6. 版本兼容

OpenSpec 中文版与英文版**完全兼容**：

```bash
# 切换到中文版
openspec-chinese update

# 切换回英文版
openspec update
```

两个版本可以在团队中并存，规范文件格式完全一致。

## 常见问题排查

### 命令不可用

**症状**：`openspec-chinese: command not found`

**解决方案**：

```bash
# 检查是否在 PATH 中
which openspec-chinese  # Mac/Linux
where openspec-chinese  # Windows

# 检查 npm 全局 bin 路径
npm config get prefix

# 重新安装
npm uninstall -g @org-hex/openspec-chinese
npm install -g @org-hex/openspec-chinese@latest
```

### 斜杠命令未出现

**症状**：AI 工具中看不到 `/openspec-*` 命令

**解决方案**：

```bash
# 执行更新命令
openspec-chinese update

# 重启 IDE/AI 工具
# 检查是否生成了 AGENTS.md
ls openspec/AGENTS.md
```

### 校验报错

**常见错误**：

1. **缺少 Delta 分区**

   ```plain
   Error: Missing required Delta sections (ADDED/MODIFIED/REMOVED)
   ```

   解决：确保至少有一个 Delta 分区

2. **缺少 MUST/SHALL 关键词**

   ```plain
   Error: Requirement missing mandatory keywords
   ```

   解决：在需求描述中添加 MUST/SHALL/SHOULD

3. **Scenario 层级错误**

   ```plain
   Error: Scenario must be under a Requirement
   ```

   解决：确保 `#### Scenario:` 在 `### Requirement:` 之下

4. **Gherkin 关键字使用中文**
   ```plain
   Error: Gherkin keywords must be in English
   ```
   解决：使用 WHEN/THEN/AND 而非"当/那么/并且"

### 归档失败

**症状**：`openspec-chinese archive` 报错

**可能原因**：

- 变更未通过校验
- specs/ 目录为空
- Git 冲突

**解决方案**：

```bash
# 先校验格式
openspec-chinese validate <change> --strict

# 检查 specs/ 目录
ls openspec/changes/<change>/specs/

# 解决 Git 冲突后重试
git status
```

## 触发场景

本技能应在以下场景**主动调用**：

### 明确触发

1. 用户提及 "openspec"
2. 用户提及 "规范文档"、"需求文档"
3. 用户提及 "spec-driven development"
4. 用户询问如何管理需求

### 上下文触发

5. 用户开始新功能开发前（建议使用 OpenSpec）
6. 用户抱怨 AI 理解偏差或频繁返工
7. 用户询问如何让 AI 更准确理解需求
8. 用户需要生成技术文档

### 项目阶段触发

9. 项目初始化阶段（建议配置 OpenSpec）
10. 准备重大重构时（建议先写规范）
11. 团队协作场景（提供统一的需求描述）

## 执行长任务时的注意事项

1. **及时更新任务文件**：
   > **必须要**及时更新对应任务的 `tasks.md` 任务进度文件。避免出现大批量完成任务后，没有更新进度文件的情况，带来严重的误解。
2. 启动**多个子代理**分模块并行完成任务：
   > 务必要启动多个在后台运行的子代理，同时完成 openspec 设定的一系列繁杂的任务。以便加快速度。你应该至少同时启用至少 4 个子代理。并根据情况，主动增加足够数量的子代理完成任务。
3. 回复文本语言：
   > 务必用**中文**回复用户。
4. 上下文合并后重新阅读一次任务要求：
   > 为了避免你在自动合并上下文的时候，给后续的任务带来明显的幻觉，你应该及时的重新阅读 openspec 的任务规范要求。
5. 连续的，持续的执行长任务：
   - 你应该一次性完成 `tasks.md` 所记录的全部任务。你应该同时新建多个子代理，做出合理的任务划分，一次性完成任务。
   - 不要在完成一个任务的时候就停下来询问用户。这种停顿方式很低效率，你要避免这种执行方式。
6. **禁止**编写脚本完成批处理任务：
   - **不允许**你编写任何 Python、typescript、javascript，或 bash 脚本，完成大批量代码删改之类的任务。
   - 你应该阅读文件来完成更改，而不是使用不稳定的，容易带来语法错误的，删改不干净不合理的批处理脚本，来完成任务。
   - 你应该新建多个子代理，用具体的子代理来完成大规模的修改任务。
7. 主从代理的调度设计：
   - `主代理的职责`： 主代理应该负责全面的，完整的阅读来自 openspec 目录下全部的 markdown 文档任务要求。并按照模块和错误类型，新建足够数量的子代理。并持续监听，定期收集来自子代理的处理反馈。
   - `子代理的职责`： 子代理应该严格按照主代理给定的要求来完成任务。
8. 什么情况下应该新建子代理？在以下的几种情况下，主代理应该及时新建子代理来完成任务：
   - 大规模的代码探索与信息收集任务。
   - 访问 url 获取文档信息的任务。
   - 指定严格顺序的代码修改任务。
   - 报告编写任务。
   - 进度文件更新与编写任务。

## 注意事项

### 格式要求（严格遵守）

1. ✅ Delta 分区标题必须使用**英文**（ADDED/MODIFIED/REMOVED）
2. ✅ Gherkin 关键字必须使用**英文**（WHEN/THEN/AND/GIVEN）
3. ✅ 需求描述中必须包含 MUST/SHALL/SHOULD 等**强制关键词**
4. ✅ 删除需求时必须提供 **Reason** 和 **Migration**
5. ✅ 每个 Requirement 至少有**一个 Scenario**

### 工作流建议

1. ⏰ 提案阶段多花时间，实施阶段会快很多
2. 📝 规格要具体可验证，能直接转化为测试用例
3. ✅ 每次编辑后立即运行 `validate --strict`
4. 🔄 保持规范与代码同步，归档前再次审查
5. 📚 善用 `project.md` 提供项目上下文

### 团队协作

1. 👥 规范文件适合 Code Review
2. 📖 `changes/` 目录中的提案可作为 PR 描述
3. 🔍 归档后的 `specs/` 成为团队共识
4. 🌍 中英文版本可并存，格式完全兼容

### 工具集成

1. 🤖 支持 20+ AI 编程工具，无缝集成
2. 🔒 完全本地执行，无需 API 密钥
3. 📂 AGENTS.md 提供通用兼容性
4. ⚡ 斜杠命令提供快捷操作

---

## 参考资源

- **OpenSpec 中文版仓库**: https://github.com/hex-novaflow-ai/OpenSpec-Chinese
- **OpenSpec 原版仓库**: https://github.com/Fission-AI/OpenSpec
- **介绍教程**: https://www.aivi.fyi/llms/introduce-OpenSpec
- **官方文档**: 项目 README 和 docs 目录

全局 agents.md 推荐：

AGENTS.md.txt

config 是与服务器 "打交道" 的配置，Agents. 是操作指南，告诉 Ai 在操作 Project 如何去做。
比如是一辆车，如果 Agents 是大脑是车机控制系统，来操作车的自动驾驶。那么 config 就是底盘。通过 config 切换不同底盘。

“道路 " 就是我们的项目，Agents.md 写的太好，底盘不好，驾驶起来照样别扭。想象一下你是全国第一赛车手，但是你驾驶的是一辆老头乐，那么必然发挥不出来。

这就是木桶效应！！！所以我们一定要对齐短板。

OpenCode 配置指南

配置文件位置

• 主配置文件: ~/.config/opencode/opencode.json (供应商和模型配置)
• 认证文件: ~/.local/share/opencode/auth.json (API Key 存储)
• 全局提示词: ~/.config/opencode/AGENTS.md (全局行为规范)
• 项目提示词: <项目根目录>/AGENTS.md (项目特定规范)

快速配置步骤

1. 配置供应商

在 ~/.config/opencode/opencode.json 中添加供应商配置:

{ "$schema": "https://opencode.ai/config.json", "provider": { "供应商名称": { "options": { "baseURL": "https://api.供应商域名.com/v1" }, "models": {} } } } 

参数说明:

• 供应商名称: 自定义供应商名称 (如 claude、openai、智谱 ai、xxx 中转站 `)
• baseURL: API 服务的基础 URL

2. 配置 API Key

方式一：使用命令行 (推荐)

# 登录或更新某个供应商的 Key
opencode auth login

# 查看当前已配置的所有供应商和 Key 状态
opencode auth list

# 删除指定供应商的 Key
opencode auth logout <供应商名称>

方式二：手动编辑配置文件

在 ~/.local/share/opencode/auth.json 中添加对应供应商的 API Key:

{ "供应商名称": { "type": "api", "key": "你的API密钥" } } 

注意: auth.json 中的供应商名称必须与 opencode.json 中的供应商名称完全一致。

3. 配置模型

在供应商下添加模型配置:

{ "provider": { "供应商名称": { "options": { "baseURL": "https://api.供应商域名.com/v1" }, "models": { "claude-sonnet-4-5-20250929": { "id": "claude-sonnet-4-5-20250929", "name": "Claude Sonnet 4.5", "cost": { "input": 3, "output": 15 }, "limit": { "context": 200000, "output": 64000 }, "reasoning": true, "temperature": true, "tool_call": true, "attachment": true } } } } } 

模型参数说明:

API Key 管理

优先级机制

OpenCode 选择 API Key 的优先级如下:

1. 环境变量 (最高优先级)

   • 例如: ANTHROPIC_API_KEY、OPENAI_API_KEY 或 OPENCODE_<供应商名称>_APIKEY
   • 只要设置了环境变量，优先使用环境变量中的值

2. 本地配置文件 (备选)

   • 如果没有设置环境变量，才使用 ~/.local/share/opencode/auth.json 中的 Key
   • 此时使用的是该供应商最后一次执行 auth login 时输入的 Key

覆盖机制

• 对同一个供应商多次执行 opencode auth login，后一次登录会覆盖前一次的 Key
• 环境变量始终优先于配置文件

配置示例

完整配置示例

opencode.json:

{ "$schema": "https://opencode.ai/config.json", "provider": { "供应商1": { "options": { "baseURL": "https://api.供应商1域名.com/v1" }, "models": { "claude-sonnet-4-5-20250929": { "id": "claude-sonnet-4-5-20250929", "name": "Claude Sonnet 4.5", "cost": { "input": 3, "output": 15 }, "limit": { "context": 200000, "output": 64000 }, "reasoning": true, "temperature": true, "tool_call": true, "attachment": true } } }, "供应商2": { "options": { "baseURL": "https://api.供应商2域名.com/v1" }, "models": { "claude-haiku-4-5-20251001": { "id": "claude-haiku-4-5-20251001", "name": "Claude Haiku 4.5", "cost": { "input": 1, "output": 5 }, "limit": { "context": 200000, "output": 64000 }, "reasoning": true, "temperature": true, "tool_call": true, "attachment": true } } } } } 

auth.json:

{ "供应商1": { "type": "api", "key": "你的API密钥1" }, "供应商2": { "type": "api", "key": "你的API密钥2" } } 

安全建议

1. 文件权限

   • 设置 auth.json 为仅当前用户可读: chmod 600 ~/.local/share/opencode/auth.json
   • 不要将 auth.json 提交到版本控制系统

2. 环境隔离

   • 开发环境和生产环境使用不同的 API Key
   • 推荐使用环境变量或项目根目录下的 .env 文件管理 Key
   • 确保 .env 已加入 .gitignore

3. Key 管理

   • 定期轮换 API Key
   • 使用具有适当权限限制的 API Key
   • auth.json 目前为明文存储，请勿随意分享

4. 备份

   • 建议定期备份配置文件
   • auth.json 备份时注意安全存储

提示词配置

OpenCode 支持通过 AGENTS.md 文件自定义 AI 助手的行为规范和工作流程。

提示词类型

OpenCode 提供两种级别的提示词配置:

1. 全局提示词 - 对所有项目生效
2. 项目提示词 - 仅对当前项目生效

提示词文件位置

优先级机制

当同时存在全局和项目提示词时:

• 项目提示词优先级更高，会覆盖全局提示词中的相同配置
• 两者会合并使用，项目提示词补充项目特定的规范

提示词内容示例

全局提示词 (~/.config/opencode/AGENTS.md):

# OpenCode 全局提示词 ## 核心原则 - 严谨工作态度，保证完美质量标准
- 直接输出代码或方案，禁止客套话
- 回复简洁明了，使用中文

## 代码规范 - 遵循项目现有代码风格
- 优先编写直观的线性逻辑
- 考虑边界条件和极端情况

## Git 工作流 - 仅在明确要求时提交
- 遵循约定式提交消息格式
- 提交前检查 git status 和 git diff

项目提示词 (<项目根目录>/AGENTS.md):

# 项目名称 - 项目特定提示词 ## 项目概述
这是一个 XXX 项目，使用 XXX 技术栈。

## 目录结构 

project/
├── src/ # 源代码
├── tests/ # 测试文件
└── docs/ # 文档

 ## 项目规范 - 使用 TypeScript 严格模式
- 测试覆盖率要求 80% 以上
- 所有 API 必须有 JSDoc 注释

## 工作流程 1. 修改代码前先运行测试
2. 完成后运行 `npm run lint` 和 `npm test` 3. 提交信息格式: `<type>(<scope>): <subject>` 

提示词配置建议

1. 全局提示词

   • 定义通用的代码规范和工作原则
   • 设置统一的命名规范和注释风格
   • 配置 Git 提交规范

2. 项目提示词

   • 说明项目的技术栈和架构
   • 描述项目特定的目录结构
   • 定义项目特有的工作流程和规范
   • 列出项目常用的命令和工具

3. 最佳实践

   • 保持提示词简洁明确，避免冗长描述
   • 使用 Markdown 格式，便于阅读和维护
   • 定期更新提示词，与项目演进保持同步
   • 将敏感信息（如密码、密钥）排除在提示词之外

如何创建提示词文件

创建全局提示词:

# 创建配置目录（如果不存在） mkdir -p ~/.config/opencode

# 创建全局提示词文件 touch ~/.config/opencode/AGENTS.md

# 编辑文件
vim ~/.config/opencode/AGENTS.md

创建项目提示词:

# 在项目根目录创建 cd /path/to/项目目录
touch AGENTS.md

# 编辑文件
vim AGENTS.md

# 建议将 AGENTS.md 加入版本控制
git add AGENTS.md
git commit -m "docs: add project-specific agent instructions" 

提示词生效时机

• 全局提示词: OpenCode 启动时自动加载
• 项目提示词: 打开项目目录时自动加载
• 修改后: 需要重启 OpenCode 或重新打开项目才能生效

常见问题

如何添加新的 API 供应商？

1. 在 opencode.json 中添加供应商配置 (baseURL 和 models)
2. 在 auth.json 中添加对应的 API Key 或使用 opencode auth login
3. 重启 OpenCode

如何切换不同的模型？

在 OpenCode 界面中按 Ctrl+P，选择 “Switch Model” 即可切换已配置的模型。

如何验证配置是否正确？

启动 OpenCode 后，尝试发送一条消息。如果配置正确，模型会正常响应。如果出错，检查:

• 供应商名称是否在两个文件中一致
• API Key 是否正确
• baseURL 是否可访问

支持哪些 API 供应商？

OpenCode 支持所有兼容 OpenAI API 格式的供应商，包括:

• Anthropic Claude
• OpenAI GPT
• Azure OpenAI
• 智谱 AI
• 各类第三方 API 代理服务

环境变量和配置文件同时存在时使用哪个？

环境变量优先级更高。如果设置了环境变量 (如 ANTHROPIC_API_KEY)，OpenCode 会优先使用环境变量中的 Key，忽略 auth.json 中的配置。

更多帮助

• 官方文档: Intro | OpenCode
• 问题反馈: GitHub - anomalyco/opencode: The open source coding agent.
• 按 Ctrl+P 查看所有可用操作

之前没用过 Augment，跟着帖子 Augment-BYOK 配合反重力个人配置经验分享尝试配置体验了下，有几点需要补充

1、使用 Augment-BYOK 配合站内的公益站不需要拥有 Augment 账号。配置好后显示就是登录状态，基础功能包括 ace 索引、agent、chat、提示词增强、tab 都可以使用，但是有些小问题。

先说下配置方法：

• 下载 @Ank 大佬开发的 BYOK 插件 github

• vscode 安装插件后提示登录，从命令框搜索 byok，打开配置页面

  

• BaseURL 输入 @heromantf 大佬的转发地址 https://acemcp.heroman.wtf/relay/ 和管理后台获取的 key

• 这个时候点测试是不通的，可能因为 key 还没保存，先点一下保存配置再测试

  

• 模型提供商配置里，OpenAI chat、responses、Anthropic 三种模式是都可用的，不一定非要 Anthropic 格式，设置好后也要先点一下保存设置，key 标签才会变绿

  

• 功能路由，就是除了 chat 和 agent 的一些内置功能使用什么模型。这里最好配置响应快的模型，让 ai 翻译了下功能名称如下

  

2、配置好后大致体验了下，发现几个问题

• 不能调用远程工具，比如 web-search，这个应该是 ralay 站没有转发相关请求

  
  
  
  

• tab 功能有提示，但是我抓包看了下没有上传上下文，提示的很混乱，不知道是不是配置问题

  

初步印象 Augment 的交互设计的还是挺好的，有空了再深入体验下

之前分享了一个 opencode 的配置，大家也给我提了很多意见，感谢大家！！！

但是我在使用 opencode 的时候当上下文快满的时候自动进行上下文压缩，但是会报错，然后我尝试了手动压缩 /compact 指令，我发现了一个很有意思的现象，当我不使用工具调用的时候可以正常压缩，但是我只要使用工具调用就报错：Bad Request: Improperly formed request. 所以我就猜测是因为思考块里面带了工具调用，致使 CPA 不支持，所以我就开始改 CPA，修复逻辑如下

然后吭哧吭哧改了两天，调了很多次，最后可以正常压缩了，但是工具调用的时候一直循环，无奈宣告失败。。。

但是，我在查文档的时候发现压缩上下文的也是一个子代理，默认使用的是主模型，那既然这样，我换一个模型不就行了，直接开干，因为我设置了 google 的 api 所以我用的是 google 模型。

正常工作，果然，opencode 的高自定义程度名不虚传，好玩爱玩，如果有佬有更好的方法，欢迎分享，在此献上我的 opencode.json 文件，大家可以看看：

{
  "$schema": "https://opencode.ai/config.json",
  "model": "cpa-claude/kiro-claude-opus-4-5-agentic(high)",
  "agent": {
    "compaction": {
      "model": "google/antigravity-gemini-3-pro-low"
    }
  },
  "plugin": [
    "oh-my-opencode",
    "opencode-antigravity-auth@1.2.8",
    "opencode-openai-codex-auth@4.3.0"
  ],
  "provider": {
    "cpa-claude": {
      "npm": "@ai-sdk/anthropic",
      "name": "cpa-claude",
      "options": {
        "baseURL": "http://127.0.0.1:8317/v1"},
      "models": {
        "gemini-claude-opus-4-5-thinking(high)": {
          "name": "gemini-claude-opus-4-5-thinking(high)",
          "limit": {
            "context": 204800,
            "output": 65535
          },
          "modalities": {
            "input": [
              "text",
              "image",
              "pdf"
            ],
            "output": [
              "text"
            ]
          },
          "options": {
            "thinking": {
              "type": "enabled",
              "budgetTokens": 16000
            }
          }
        },
        "gemini-claude-sonnet-4-5-thinking(high)": {
          "name": "gemini-claude-sonnet-4-5-thinking(high)",
          "limit": {
            "context": 204800,
            "output": 65535
          },
          "modalities": {
            "input": [
              "text",
              "image",
              "pdf"
            ],
            "output": [
              "text"
            ]
          },
          "options": {
            "thinking": {
              "type": "enabled",
              "budgetTokens": 16000
            }
          }
        },
        "kiro-claude-sonnet-4-5-agentic": {
          "name": "claude-sonnet-4-5-nothinking",
          "limit": {
            "context": 204800,
            "output": 65535
          },
          "modalities": {
            "input": [
              "text",
              "image",
              "pdf"
            ],
            "output": [
              "text"
            ]
          }
        },
        "kiro-claude-sonnet-4-5-agentic(high)": {
          "name": "claude-sonnet-4-5",
          "limit": {
            "context": 204800,
            "output": 65535
          },
          "modalities": {
            "input": [
              "text",
              "image",
              "pdf"
            ],
            "output": [
              "text"
            ]
          },
          "options": {
            "thinking": {
              "type": "enabled",
              "budgetTokens": 16000
            }
          }
        },
        "kiro-claude-opus-4-5-agentic(high)": {
          "name": "claude-opus-4-5",
          "limit": {
            "context": 204800,
            "output": 65535
          },
          "modalities": {
            "input": [
              "text",
              "image",
              "pdf"
            ],
            "output": [
              "text"
            ]
          },
          "options": {
            "thinking": {
              "type": "enabled",
              "budgetTokens": 16000
            }
          }
        }
      }
    },
    "cpa-gemini": {
      "name": "cpa-gemini",
      "options": {
        "baseURL": "http://127.0.0.1:8317/v1"
      },
      "models": {
        "gemini-3-pro-preview": {
          "name": "gemini-3-pro-preview",
          "limit": {
            "context": 1048576,
            "output": 65535
          },
          "modalities": {
            "input": [
              "text",
              "image",
              "pdf"
            ],
            "output": [
              "text"
            ]
          },
          "options": {
            "thinking": {
              "type": "enabled",
              "budgetTokens": 16000
            }
          }
        },
        "gemini-3-flash-preview": {
          "name": "gemini-3-flash-preview",
          "limit": {
            "context": 1048576,
            "output": 65536
          },
          "modalities": {
            "input": [
              "text",
              "image",
              "pdf"
            ],
            "output": [
              "text"
            ]
          },
          "options": {
            "thinking": {
              "type": "enabled",
              "budgetTokens": 16000
            }
          }
        }
      }
    },
    "google": {
      "name": "Google",
      "models": {
        "antigravity-gemini-3-pro-high": {
          "name": "Gemini 3 Pro High (Antigravity)",
          "thinking": true,
          "attachment": true,
          "limit": {
            "context": 1048576,
            "output": 65535
          },
          "modalities": {
            "input": [
              "text",
              "image",
              "pdf"
            ],
            "output": [
              "text"
            ]
          }
        },
        "antigravity-gemini-3-pro-low": {
          "name": "Gemini 3 Pro Low (Antigravity)",
          "thinking": true,
          "attachment": true,
          "limit": {
            "context": 1048576,
            "output": 65535
          },
          "modalities": {
            "input": [
              "text",
              "image",
              "pdf"
            ],
            "output": [
              "text"
            ]
          }
        },
        "antigravity-gemini-3-flash": {
          "name": "Gemini 3 Flash (Antigravity)",
          "attachment": true,
          "limit": {
            "context": 1048576,
            "output": 65536
          },
          "modalities": {
            "input": [
              "text",
              "image",
              "pdf"
            ],
            "output": [
              "text"
            ]
          }
        }
      }
    },
    "openai": {
      "name": "OpenAI",
      "options": {
        "reasoningEffort": "medium",
        "reasoningSummary": "auto",
        "textVerbosity": "medium",
        "include": [
          "reasoning.encrypted_content"
        ],
        "store": false
      },
      "models": {
        "gpt-5.2": {
          "name": "GPT 5.2 (OAuth)",
          "limit": {
            "context": 272000,
            "output": 128000
          },
          "modalities": {
            "input": [
              "text",
              "image"
            ],
            "output": [
              "text"
            ]
          },
          "variants": {
            "none": {
              "reasoningEffort": "none",
              "reasoningSummary": "auto",
              "textVerbosity": "medium"
            },
            "low": {
              "reasoningEffort": "low",
              "reasoningSummary": "auto",
              "textVerbosity": "medium"
            },
            "medium": {
              "reasoningEffort": "medium",
              "reasoningSummary": "auto",
              "textVerbosity": "medium"
            },
            "high": {
              "reasoningEffort": "high",
              "reasoningSummary": "detailed",
              "textVerbosity": "medium"
            },
            "xhigh": {
              "reasoningEffort": "xhigh",
              "reasoningSummary": "detailed",
              "textVerbosity": "medium"
            }
          }
        },
        "gpt-5.2-codex": {
          "name": "GPT 5.2 Codex (OAuth)",
          "limit": {
            "context": 272000,
            "output": 128000
          },
          "modalities": {
            "input": [
              "text",
              "image"
            ],
            "output": [
              "text"
            ]
          },
          "variants": {
            "low": {
              "reasoningEffort": "low",
              "reasoningSummary": "auto",
              "textVerbosity": "medium"
            },
            "medium": {
              "reasoningEffort": "medium",
              "reasoningSummary": "auto",
              "textVerbosity": "medium"
            },
            "high": {
              "reasoningEffort": "high",
              "reasoningSummary": "detailed",
              "textVerbosity": "medium"
            },
            "xhigh": {
              "reasoningEffort": "xhigh",
              "reasoningSummary": "detailed",
              "textVerbosity": "medium"
            }
          }
        },
        "gpt-5.1-codex-max": {
          "name": "GPT 5.1 Codex Max (OAuth)",
          "limit": {
            "context": 272000,
            "output": 128000
          },
          "modalities": {
            "input": [
              "text",
              "image"
            ],
            "output": [
              "text"
            ]
          },
          "variants": {
            "low": {
              "reasoningEffort": "low",
              "reasoningSummary": "detailed",
              "textVerbosity": "medium"
            },
            "medium": {
              "reasoningEffort": "medium",
              "reasoningSummary": "detailed",
              "textVerbosity": "medium"
            },
            "high": {
              "reasoningEffort": "high",
              "reasoningSummary": "detailed",
              "textVerbosity": "medium"
            },
            "xhigh": {
              "reasoningEffort": "xhigh",
              "reasoningSummary": "detailed",
              "textVerbosity": "medium"
            }
          }
        }
      }
    }
  }
}

除了使用 google/antigravity-gemini-3-pro-low 还可以使用 opencode 提供的免费模型，比如 GLM4.7。

当然，这个只是一个曲线救国的方法，如果有佬有更好的方法，欢迎分享！！！

配置问题可以看看之前那个帖子

使用方法：用 vscode 打开你本地 vscode 所在目录的 index-C-orm5fu.js 文件 (具体文件名、路径可能会根据每个人的操作系统、个人配置有所不同，请自行替换。我是 win10)。

**

注意修改前请自行备份 index-C-orm5fu.js 文件，以防修改错误导致 codex 插件不可用。

**

在模型选择中，直接使用当前可用的模型，如 5.1\5.2 等，输入以下提示词：

==================================================================
帮我在当前 C:\Users\Administrator.vscode\extensions\openai.chatgpt-0.4.58-win32-x64\webview\assets\index-C-orm5fu.js 中，调整模型顺序
搜索 MODEL_ORDER_BY_AUTH_METHOD。
在 apikey: 列表最前添加 / 确保有 gpt-5.2-codex（与 chatgpt 列表一致）。
放宽仅 ChatGPT 登录限制

搜索 CHAT_GPT_AUTH_ONLY_MODELS。
列表里只保留 codex-auto；删除可能存在的 gpt-5.2-codex。
防止默认回退（关键一步）

搜索片段 CHAT_GPT_AUTH_ONLY_MODELS.has (normalizeModel (mt))。
你会看到类似条件：… && !lt && !!mt && CHAT_GPT_AUTH_ONLY_MODELS.has (normalizeModel (mt))
在！lt 后面插入 Ye!==“apikey” &&（Ye 是当前 authMethod），改成：
… && !lt && Ye!==“apikey” && !!mt && CHAT_GPT_AUTH_ONLY_MODELS.has(normalizeModel(mt))
含义：只有非 apikey 且模型在该集合时才强制回退；apikey 不回退。

==================================================================

完成后重启一下 codex 插件或者 vscode 后，gpt-5.2-codex 模型就可以直接选择使用了

之前有佬友发了白嫖老黄的 nvidia/minimax-m2.1 模型

正好最近在试用 opencode，就尝试配置了一下，放出配置文件给大家参考下 ~/.config/opencode/opencode.json

{ "$schema": "https://opencode.ai/config.json", "mcp": { "augment-context-engine": { "type": "local", "command": [ "auggie", "--mcp" ], "enabled": true }, "sequential": { "type": "local", "command": [ "npx", "@modelcontextprotocol/server-sequential-thinking" ], "enabled": true }, "playwright": { "type": "local", "command": [ "npx", "@playwright/mcp@latest" ], "enabled": true }, "context7": { "type": "local", "command": [ "npx", "@upstash/context7-mcp@latest" ], "enabled": true } }, "provider": { "nvidia": { "npm": "@ai-sdk/openai-compatible", "options": { "baseURL": "https://integrate.api.nvidia.com/v1", "apiKey": "你的 apikey" }, "models": { "minimax-m2.1": { "id": "minimaxai/minimax-m2.1" } } } }, "model": "nvidia/minimax-m2.1" } 

配置好之后重启 opencode，就可以看到模型生效拉

当然 Kilo 也可以跑，配置起来更简单，这里就不放配置了

OpenCode 使用 CLIProxyAPI 作为模型提供商的步骤

写在前面：不要质疑我的某些操作，虽然繁琐，但自有深意。例如为什么我要将 CPA 的提供商分为 4 个，以及为什么要这样配置常用模型。如果存在意见不合，那就是你对。

opencode 作为开源的终端代理，配合 ohmyopencode 使用，是目前十分推荐且前沿的玩法，核心是异步子代理协作（也就是十分烧钱），虽然官方提供了免费的 minimax2.1 和其他几个模型，但使用高级子代理完成前端设计、审查时，仍然需要用高级模型，为此特意写了这个教程，供佬们参考。
难点：opencode 将 key 和 Provider 配置分离储存，且需要自行选择对应的 sdk，避免格式问题，以下配置中已包含推荐用法。

1. 绑定 API 密钥

在 OpenCode 终端执行以下操作，为四个自定义 ID 注册凭据：

1. 终端执行命令：opencode auth login 注意不是在 opencode 里执行
2. 选择 Other（这里不需要手动滚动，很累，直接输入 other，会自动列出）
3. 依次创建以下 ID 并粘贴 API Key：

• cpa
• cpa-oai
• cpa-claude
• cpa-gemini

2. 修改配置文件

编辑全局的 opencode.json（ macOS / Linux: ~/.config/opencode/ Windows: Users\你的用户名\ .config\opencode），将以下内容整合进 provider 字段，我给出的仅供参考，不会就直接复制，删掉自己不要的模型即可。所有模型已开启 thinking 模式 （未来官方可能会弃用该字段） ，并按协议类型匹配了 SDK。

{ "$schema": "https://opencode.ai/config.json", "plugin": [ "oh-my-opencode"], "provider": { "cpa": { "npm": "@ai-sdk/openai-compatible", "name": "cpa", "options": { "baseURL": "https://<YOUR_ENDPOINT>/v1" }, "models": { "kimi-k2-thinking": { "name": "kimi-k2-thinking", "thinking": true }, "glm-4.7": { "name": "glm-4.7", "thinking": true } } }, "cpa-oai": { "npm": "@ai-sdk/openai", "name": "cpa-oai", "options": { "baseURL": "https://<YOUR_ENDPOINT>/v1" }, "models": { "gpt-5.2": { "name": "gpt-5.2", "thinking": true }, "gpt-5.1-codex-max": { "name": "gpt-5.1-codex-max", "thinking": true } } }, "cpa-claude": { "npm": "@ai-sdk/anthropic", "name": "cpa-claude", "options": { "baseURL": "https://<YOUR_ENDPOINT>/v1" }, "models": { "gemini-claude-opus-4-5-thinking": { "name": "gemini-claude-opus-4-5-thinking", "thinking": true }, "gemini-claude-sonnet-4-5-thinking": { "name": "gemini-claude-sonnet-4-5-thinking", "thinking": true }, "claude-opus-4-5-20251101": { "name": "claude-opus-4-5-20251101", "thinking": true }, "claude-sonnet-4-5-20250929": { "name": "claude-sonnet-4-5-20250929", "thinking": true }, "claude-haiku-4-5-20251001": { "name": "claude-haiku-4-5-20251001", "thinking": true }, "claude-kimi": { "name": "claude-kimi", "thinking": true } } }, "cpa-gemini": { "npm": "@ai-sdk/google", "name": "cpa-gemini", "options": { "baseURL": "https://<YOUR_ENDPOINT>/v1beta" }, "models": { "gemini-3-pro-preview": { "name": "gemini-3-pro-preview", "thinking": true }, "gemini-3-flash-preview": { "name": "gemini-3-flash-preview", "thinking": true }, "gemini-2.5-flash-lite": { "name": "gemini-2.5-flash-lite", "thinking": true } } } } } 

3. 切换模型

1. 重载：保存文件，OpenCode 自动生效。
2. 选择：输入 /models 弹出列表。
3. 识别：根据 cpa-* 前缀找到对应模型，回车确认。

（PS：模型回复为 3.7 模型，是因为 CPA 内置了一部分提示词的干扰，无影响）

额外补充

不建议通过 cpa 反代 codex 再接入 opencode，当前版本的 cpa 和 opencode 似乎有兼容性问题，会导致模型列表消失，需要重新登录凭证。（多个群友复现）
建议使用 ohmyopencode 直接 oauth 登录 codex