AiCodeCat Docs

主题

1. 安装 Node.js ​

OpenCode 需要 Node.js 环境才能运行。 最低要求：Node.js >=18（建议 LTS）。

方法一：官网下载（推荐） ​

  1. 访问 Node.js官网 下载 macOS LTS 版本
  2. 双击 .pkg 安装包并按向导完成安装

方法二：Homebrew 安装 ​

bash
brew install node

验证安装 ​

bash
node --version
npm --version

2. 安装 OpenCode ​

bash
npm install -g opencode

验证安装：

bash
opencode --version

安装问题排查

如遇到安装问题，可参考 OpenCode 安装教程。

3. 配置 API 连接 ​

获取 API 密钥 ​

在配置 OpenCode 之前，您需要先从平台获取 API 密钥。

本平台支持同时接入 Claude、OpenAI、Google 三个厂家的大模型。您需要为每个厂家分别生成独立的 API Key：

  1. 访问 API 密钥管理页面
  2. 点击"创建密钥"按钮
  3. 选择服务类型/分组：
    • Claude：选择 Claude 相关服务
    • OpenAI：选择 OpenAI/Codex 相关服务
    • Google：选择 Google/Gemini 相关服务
  4. 为每个密钥设置易于识别的名称（如"OpenCode-Claude"、"OpenCode-OpenAI"、"OpenCode-Google"）
  5. 生成后妥善保存三个密钥，稍后将分别填入配置文件

TIP

建议为每个服务生成独立的密钥，便于后续管理和追踪使用情况。

配置文件路径 ​

OpenCode 的配置文件位于用户目录下：

~/.config/opencode/opencode.json

创建配置文件 ​

bash
# 创建配置目录
mkdir -p ~/.config/opencode

# 创建配置文件
touch ~/.config/opencode/opencode.json

配置内容 ​

{
  "$schema": "https://opencode.ai/config.json",
  "tui": {
    "scroll_speed": 2,
    "scroll_acceleration": {
      "enabled": true
    },
    "diff_style": "auto"
  },
  "provider": {
    "Google": {
      "npm": "@ai-sdk/google",
      "name": "AiCodeCat Google",
      "options": {
        "baseURL": "https://aicode.cat/v1beta",
        "apiKey": "你的API密钥",
        "timeout": 600000
      },
      "models": {
        "gemini-3-pro-preview": {
          "id": "gemini-3-pro-preview",
          "name": "Gemini 3 Pro Preview",
          "family": "gemini-pro",
          "attachment": true,
          "reasoning": true,
          "tool_call": true,
          "temperature": true,
          "release_date": "2025-11-18",
          "modalities": {
            "input": ["text", "image", "video", "audio", "pdf"],
            "output": ["text"]
          },
          "cost": {
            "input": 2,
            "output": 12,
            "cache_read": 0.2,
            "context_over_200k": {
              "input": 4,
              "output": 18,
              "cache_read": 0.4
            }
          },
          "limit": {
            "context": 1048576,
            "output": 65536
          }
        },
        "gemini-3-flash-preview": {
          "id": "gemini-3-flash-preview",
          "name": "Gemini 3 Flash Preview",
          "family": "gemini-flash",
          "attachment": true,
          "reasoning": true,
          "tool_call": true,
          "temperature": true,
          "release_date": "2025-12-17",
          "modalities": {
            "input": ["text", "image", "video", "audio", "pdf"],
            "output": ["text"]
          },
          "cost": {
            "input": 0.5,
            "output": 3,
            "cache_read": 0.05,
            "context_over_200k": {
              "input": 0.5,
              "output": 3,
              "cache_read": 0.05
            }
          },
          "limit": {
            "context": 1048576,
            "output": 65536
          }
        }
      }
    },
    "ClaudeCode": {
      "npm": "@ai-sdk/anthropic",
      "name": "AiCodeCat Claude",
      "options": {
        "baseURL": "https://aicode.cat/v1",
        "apiKey": "你的API密钥",
        "timeout": 600000
      },
      "models": {
        "claude-haiku-4-5-20251001": {
          "id": "claude-haiku-4-5-20251001",
          "name": "Claude Haiku 4.5",
          "attachment": true,
          "reasoning": true,
          "tool_call": true,
          "temperature": true,
          "release_date": "2025-10-15",
          "modalities": {
            "input": ["text", "image", "pdf"],
            "output": ["text"]
          },
          "cost": {
            "input": 1,
            "output": 5,
            "cache_read": 0.1,
            "cache_write": 1.25
          },
          "limit": {
            "context": 200000,
            "output": 64000
          },
          "options": {
            "thinking": {
              "type": "enabled",
              "budgetTokens": 32000
            }
          }
        },
        "claude-sonnet-4-5-20250929": {
          "id": "claude-sonnet-4-5-20250929",
          "name": "Claude Sonnet 4.5",
          "attachment": true,
          "reasoning": true,
          "tool_call": true,
          "temperature": true,
          "release_date": "2025-09-29",
          "modalities": {
            "input": ["text", "image"],
            "output": ["text"]
          },
          "cost": {
            "input": 3,
            "output": 15,
            "cache_read": 0.3,
            "cache_write": 3.75
          },
          "limit": {
            "context": 200000,
            "output": 64000
          },
          "options": {
            "thinking": {
              "type": "enabled",
              "budgetTokens": 32000
            }
          }
        },
        "claude-opus-4-5-20251101": {
          "id": "claude-opus-4-5-20251101",
          "name": "Claude Opus 4.5",
          "attachment": true,
          "reasoning": true,
          "tool_call": true,
          "temperature": true,
          "release_date": "2025-11-24",
          "modalities": {
            "input": ["text", "image"],
            "output": ["text"]
          },
          "cost": {
            "input": 5,
            "output": 25,
            "cache_read": 0.5,
            "cache_write": 6.25
          },
          "limit": {
            "context": 200000,
            "output": 64000
          },
          "options": {
            "thinking": {
              "type": "enabled",
              "budgetTokens": 32000
            }
          }
        }
      }
    },
    "OpenAI": {
      "npm": "@ai-sdk/openai",
      "name": "AiCodeCat OpenAI",
      "options": {
        "setCacheKey": true,
        "baseURL": "https://aicode.cat/v1",
        "apiKey": "你的API密钥"
      },
      "models": {
        "gpt-5.2": {
          "name": "GPT-5.2",
          "attachment": true,
          "reasoning": true,
          "tool_call": true,
          "temperature": false,
          "cost": {
            "input": 1.75,
            "output": 14,
            "cache_read": 0.175
          },
          "limit": {
            "context": 272000,
            "output": 128000
          },
          "options": {
            "store": false,
            "reasoningEffort": "high",
            "textVerbosity": "medium",
            "reasoningSummary": "auto",
            "promptCacheKey": "opencode-stable-user",
            "include": ["reasoning.encrypted_content"]
          },
          "variants": {
            "xhigh": {
              "reasoningEffort": "xhigh",
              "textVerbosity": "medium",
              "reasoningSummary": "auto"
            },
            "high": {
              "reasoningEffort": "high",
              "textVerbosity": "medium",
              "reasoningSummary": "auto"
            },
            "medium": {
              "reasoningEffort": "medium",
              "textVerbosity": "medium",
              "reasoningSummary": "auto"
            },
            "low": {
              "reasoningEffort": "low",
              "textVerbosity": "medium",
              "reasoningSummary": "auto"
            }
          },
          "headers": {
            "x-session-id": "opencode-stable-user",
            "conversation_id": "opencode-stable-user",
            "session_id": "opencode-stable-user"
          }
        },
        "gpt-5.2-codex": {
          "name": "GPT-5.2 Codex",
          "attachment": true,
          "reasoning": true,
          "tool_call": true,
          "temperature": false,
          "cost": {
            "input": 1.75,
            "output": 14,
            "cache_read": 0.175
          },
          "limit": {
            "context": 272000,
            "output": 128000
          },
          "options": {
            "store": false,
            "reasoningEffort": "high",
            "textVerbosity": "medium",
            "reasoningSummary": "auto",
            "promptCacheKey": "opencode-stable-user",
            "include": ["reasoning.encrypted_content"]
          },
          "variants": {
            "xhigh": {
              "reasoningEffort": "xhigh",
              "textVerbosity": "medium",
              "reasoningSummary": "auto"
            },
            "high": {
              "reasoningEffort": "high",
              "textVerbosity": "medium",
              "reasoningSummary": "auto"
            },
            "medium": {
              "reasoningEffort": "medium",
              "textVerbosity": "medium",
              "reasoningSummary": "auto"
            },
            "low": {
              "reasoningEffort": "low",
              "textVerbosity": "medium",
              "reasoningSummary": "auto"
            }
          },
          "headers": {
            "x-session-id": "opencode-stable-user",
            "conversation_id": "opencode-stable-user",
            "session_id": "opencode-stable-user"
          }
        },
        "gpt-5.1-codex-max": {
          "name": "GPT-5.1-Codex-Max",
          "limit": {
            "context": 272000,
            "output": 128000
          },
          "options": {
            "store": false,
            "include": ["reasoning.encrypted_content"]
          },
          "variants": {
            "xhigh": {
              "reasoningEffort": "xhigh",
              "textVerbosity": "medium",
              "reasoningSummary": "auto"
            },
            "high": {
              "reasoningEffort": "high",
              "textVerbosity": "medium",
              "reasoningSummary": "auto"
            },
            "medium": {
              "reasoningEffort": "medium",
              "textVerbosity": "medium",
              "reasoningSummary": "auto"
            },
            "low": {
              "reasoningEffort": "low",
              "textVerbosity": "medium",
              "reasoningSummary": "auto"
            }
          }
        }
      }
    }
  }
}

WARNING

请将"你的API密钥"替换为用户仪表盘中创建的实际密钥。

配置说明

  • baseURL：API 中转服务地址（自动适配当前访问域名）
  • apiKey：从 API 密钥管理页面获取的 API 密钥
  • timeout：请求超时时间（毫秒）
  • models：可用的模型列表及其配置

4. 开始使用 ​

bash
opencode

可运行 opencode --help 查看支持的命令。

更多配置

如需了解更多配置选项，可参考：