以下將示範如何利用 Open Codex CLI 打造一個專屬的程式開發代理人（agent），讓你能透過命令列快速進行程式碼檢視、重構、測試或自動化工作。範例以 Node.js 環境為主，並採用 YAML/JSON 來設定代理人角色及工具整合。

---

## 一、前置需求

1. 已安裝 Node.js （v14+）與 npm／yarn

2. 已申請 OpenAI API 金鑰（`OPENAI_API_KEY`）

3. 已安裝 Git（如需版本控制）

---

## 二、安裝 Open Codex CLI

# 使用 npm 安裝 CLI
npm install -g @openai/codex-cli

# 確認版本
codex --version

---

## 三、設定 API 金鑰

將 金鑰設定在環境變數中，或放到使用者主目錄下的設定檔：

# Unix/macOS
export OPENAI_API_KEY="你的_api_金鑰"

# Windows PowerShell
setx OPENAI_API_KEY "你的_api_金鑰"

或在 `~/.config/codex/config.yaml` 中：

openai:
  api_key: "你的_api_金鑰"
  model: "gpt-4-codex"    # 或 gpt-3.5-codex

---

## 四、建立專案骨架

在工作目錄下初始化一個 Codex 專案：

mkdir my-dev-agent
cd my-dev-agent
codex init

這會產生：

my-dev-agent/
├── codex.yaml       # 代理人設定檔
└── src/             # 可放測試程式或範例檔

---

## 五、設定代理人角色（codex.yaml）

在 `codex.yaml` 中定義你的「代理人性格」、專長工具和記憶設定。例如：

agent:
  name: DevAssistant
  description: |
    你是一位專業的程式開發助理，精通 JavaScript、TypeScript、Node.js，
    熟悉測試（Jest）、CI/CD（GitHub Actions）與程式碼重構。
  system_prompt: |
    你將協助使用者撰寫、檢閱和重構程式碼，並給出最佳實踐建議。
  temperature: 0.2
  max_tokens: 1024

tools:
  - name: shell
    description: 執行 shell 指令與顯示結果
  - name: git
    description: 執行 git 指令並解析回傳
  - name: fs
    description: 讀寫檔案系統

memory:
  enabled: true
  type: local
  path: ./agent_memory.json

- **`agent.system_prompt`**：控制代理人整體語氣與專長領域

- **`tools`**：列出可用的工具，例如執行 shell、Git 操作或存取檔案

- **`memory`**：是否保留上下文（如問題、專案結構），以便多輪對話

---

## 六、常用 CLI 命令

| 命令 | 功能 |
| --- | --- |
| `codex chat` | 進入互動式對話模式 |
| `codex run [cmd]` | 直接向代理人下達指令（如 `codex run "fix lint"`） |
| `codex dev` | 偵測專案變動後自動觸發預設任務 |
| `codex test` | 執行代理人針對程式碼提出的測試用例 |

範例：要求重構一段程式碼

codex run "請幫我重構 src/utils.js 中的函式 calculateSum，使其更具可讀性並加上單元測試"

---

## 七、範例：自動化格式化與測試

可在 `codex.yaml` 加入一組預設任務（workflows）：

workflows:
  precommit:
    - shell: "npm run lint -- --fix"
    - shell: "npm test"
  ci:
    - git: "checkout $BRANCH"
    - shell: "npm ci"
    - shell: "npm run build"
    - shell: "npm test"

接著執行：

codex run "執行 precommit 工作流程"

Cli 會依序跑完 `lint --fix`、`npm test`，並將結果回報給你。

---

## 八、整合 VS Code

1. 安裝 “OpenAI Codex CLI” 擴充套件

2. 在工作區設定檔 `.vscode/settings.json`：

    {
      "codex.cliPath": "codex",
      "codex.agentConfig": "${workspaceFolder}/codex.yaml"
    }

3. 即可在編輯器側邊呼叫代理人：選取程式碼 → 右鍵 → “Codex: Ask Agent”

---

## 九、進階技巧

- **自定記憶觸發**：撰寫自定義 Hook，在特定檔案或目錄變動時自動將變更記錄到 `memory`。

- **複合工具**：自建工具插件（例如串接 Jira、Slack），在 `tools` 中註冊後，可讓代理人同時執行程式開發與專案管理。

- **多代理人協作**：可定義多個 YAML 配置檔，分別為「測試代理人」、「文件撰寫代理人」等，並串聯工作流程。

---

透過上述流程，你就能快速打造一個專屬於自己、且高度可客製化的程式開發代理人，無論是程式重構、測試驅動開發，或是整合 CI/CD，都能一鍵完成！若有更進階的需求或整合問題，歡迎再討論。