---
name: opencode_key_replacement_script
description: 当需要批量替换 ~/.astrion/astrion、~/.astrion/astrion-clone 和服务器 /opt/agent/runtime 中的 OpenCode API key 时，应该索引本记忆
---

---
name: opencode_key_replacement_script
description: 当需要批量替换 ~/.astrion/astrion、~/.astrion/astrion-clone 和服务器 /opt/agent/runtime 中的 OpenCode API key 时，应该索引本记忆
---

# OpenCode API key 批量替换脚本

## 脚本位置

项目根目录下的 `replace_opencode_keys.py`。

## 作用

一次性批量替换以下目录中所有 OpenCode 相关的 API key：

- 本地：`/Users/jojo/.astrion/astrion`
- 本地：`/Users/jojo/.astrion/astrion-clone`
- 服务器：`/opt/agent/runtime/`（或服务器上 `ASTRION_DATA_ROOT` 指向的目录）

## 扫描范围

仅扫描配置文件，自动跳过运行时数据：

- `settings.json`
- `config/*.json`
- 跳过 `data/`、`logs/`、对话历史等目录
- 跳过已有的 `.bak_` / `.bak` 备份文件

## 替换规则

脚本会查找已知的旧 OpenCode key 值（被多个 OpenCode Go 相关环境变量共用的同一串 key），并将其替换为新的 OpenCode key。

实际会改到的键名通常包括：

- `settings.json` 中 `env_vars` 下的：
  - `API_KEY_OPENCODE`
  - `AGENT_API_KEY`
  - `AGENT_THINKING_API_KEY`
  - `AGENT_TITLE_API_KEY`
  - 指向 `opencode.ai` 的 `API_KEY_KIMI`、`API_KEY_DEEPSEEK`、`API_KEY_QWEN`、`API_KEY_MINIMAX` 等
- `config/sub_agent_models.json` 中 `url` 为 `https://opencode.ai/zen/go/v1` 的模型条目的 `apikey`

`config/custom_models.json` 中一般使用 `${API_KEY_OPENCODE}` 变量引用，key 本身存在 `settings.json`，脚本不会直接修改它。

## 用法

```bash
# 只预览，不写入（循环轮换模式）
python3 replace_opencode_keys.py --dry-run

# 正式执行循环轮换（默认：key1→key2, key2→key3, key3→key1）
python3 replace_opencode_keys.py

# 单次指定替换（覆盖默认循环模式）
python3 replace_opencode_keys.py --old-key <旧key> --new-key <新key>
```

## 服务器替换流程

1. 确保脚本已上传至 `/opt/agent/agents/replace_opencode_keys.py`
2. 在服务器上修改脚本，把 `Path("/opt/agent/runtime")` 加入 `TARGET_DIRS`
3. 先执行 `--dry-run` 预览影响范围
4. 去掉 `--dry-run` 正式执行
5. 执行 `bash /opt/agent/refresh_agents.sh` 重启 webapp 服务使配置生效
6. 删除生成的 `.bak_时间戳` 备份文件

## 服务器执行方式建议

- **推荐**：通过 `terminal_session` 打开一个 SSH 会话，在会话里直接运行 `python3 replace_opencode_keys.py ...`
- **次选**：使用服务器虚拟环境的完整路径，例如 `/opt/agent/venv/bin/python3 replace_opencode_keys.py ...`
- **注意**：在旧版本或未重启前，通过 `run_command` 直接执行 `ssh host "python3 ..."` 时，`run_command` 可能把命令中的 `python3` 重写为本地 macOS 的 Python 绝对路径，导致远程服务器找不到解释器。该问题已在 `modules/terminal_ops/run.py` 中修复：当命令通过 `ssh` 在远程执行时，跳过 `python3`/`pip` 重写。

## 注意事项

- 执行前会自动在同级目录生成 `.bak_时间戳` 备份。
- 如果在沙箱/受限执行环境下运行，原目录不可写时脚本会把备份和修改后的文件写到项目工作区的 `opencode_key_replacement_backup/` 目录下，需要手动复制覆盖。
- 建议执行后删除生成的 `.bak_时间戳` 备份文件。
- 服务器上配置文件修改后，需要重启 webapp 服务才能生效。

## 历史记录

- 2026-06-19：使用脚本将本地两个目录的配置从主 key 替换为备用 key，并删除备份。
- 2026-06-19：将服务器 `/opt/agent/runtime/` 下的 `settings.json` 和 `config/sub_agent_models.json` 也从主 key 替换为备用 key，并删除备份。
- 2026-06-24：将服务器 `/opt/agent/runtime/` 下的 `settings.json`（9 处）和 `config/sub_agent_models.json`（1 处）从备用 key 替换回主 key，随后执行 `bash /opt/agent/refresh_agents.sh` 重启 webapp 服务，并删除备份。期间发现 `run_command` 执行 `ssh host "python3 ..."` 会错误重写 `python3` 为本地 macOS 路径，已修复 `modules/terminal_ops/run.py`。
- 2026-06-25：重构脚本为三 key 循环轮换模式（key1/key2/key3，去掉主/备用命名）。将本地 `~/.astrion/astrion` 和 `~/.astrion/astrion-clone` 的配置从 key2 替换为 key3（4 文件 20 处）。服务器尚未操作，当前仍为 key1。
- 2026-06-25：将本地 `~/.astrion/astrion` 和 `~/.astrion/astrion-clone` 的配置从 key2 替换为 key3（4 文件 20 处），删除备份。服务器仍为 key1。

## 相关 key 记录

| 说明 | Key |
|---|---|
| key1 | `sk-zNU867TGGXNKxoM0H6Pg6Jq4PYUPUOPDgMlzrOl3SS6jECRMWK5nNi6YMSsHzoZ` |
| key2 | `sk-sgt4ERgERPx2axU18PSfmenHv9zNDD3y8M5yr0p4ryhcNSm04CZsCxDHftJ9AkFD` |
| key3 | `sk-Jhvi76vJdCEQzvEdl8cAS5MIwBxBS4iTrJYSru2zCAXVnDVQpiZIvrcn9hBwkdZ4` |
| legacy（已停用，等同 key1 轮换到 key2） | `sk-j0NdTvEDoqqkKCHEAFXXYneEsuXEiOXNCgLeZARJmfYUBf2Riym7KPFWq1amkB6z` |