Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

安裝及設定 CLI

CodeMender 是自主 AI 程式碼安全代理，可掃描、驗證及修補程式碼集中的深層網路安全漏洞。執行 CodeMender 前，請先下載 CLI 並初始化工作區選項。

架構和安全模式

CodeMender 採用以本機為優先的執行模型：

託管推論引擎：代理推論、威脅模型和自動調度邏輯會在 Gemini Enterprise Agent Platform 上安全執行。 Google Cloud
本機執行 CLI：原始碼絕不會大量離開工作站或 CI/CD 容器。本機 cm CLI 工具會在您的本機沙箱中執行檔案讀取、本機建構檢查和概念驗證 (PoC) 漏洞驗證，並透過 Gemini Enterprise Agent Platform 上的 Interactions API，只將手術式程式碼片段和工具執行結果傳送至雲端後端。

環境設定

如要開始使用 CodeMender，請設定 Google Cloud 專案、下載並安裝 CLI、設定憑證，然後初始化工作區。

專案設定和 IAM 權限

下載 CLI 和設定憑證前，請確認目標 Google Cloud 專案已正確設定必要的 API 和權限。

必要 API

確認專案已啟用下列 API： Google Cloud

Vertex AI API (aiplatform.googleapis.com) - 支援串流及管理現有工作階段。
Cloud Resource Manager API (cloudresourcemanager.googleapis.com) - 驗證使用者驗證狀態和專案中繼資料。

建議的預先定義 IAM 角色

如要執行 CLI 指令，使用者必須獲派下列 IAM 角色：

Vertex AI User (roles/aiplatform.user)：允許使用者建立、串流及管理有效工作階段。

下載並安裝 CodeMender CLI

CodeMender CLI 二進位檔託管於 Artifact Registry。選擇作業系統的分頁標籤，下載並安裝 CLI。

Linux x86_64

如要下載及安裝 Linux (x86_64) 適用的 CodeMender CLI，請按照下列步驟操作：

使用下列任一方法下載套件：

gcloud CLI：執行下列指令：

gcloud artifacts generic download \
  --project=cmoc-prod \
  --location=us \
  --repository=codemender-cli-production \
  --package=cm \
  --version=stable \
  --name=cm-linux-amd64.zip \
  --destination=./

curl：執行下列指令：

curl -L -o cm-linux-amd64.zip "https://artifactregistry.googleapis.com/download/v1/projects/cmoc-prod/locations/us/repositories/codemender-cli-production/files/cm%3Astable%3Acm-linux-amd64.zip:download?alt=media"

安裝 CLI：

unzip cm-linux-amd64.zip
chmod +x cm
sudo mv cm /usr/local/bin/cm

Linux ARM64

如要下載及安裝 Linux (ARM64) 版 CodeMender CLI，請按照下列步驟操作：

使用下列任一方法下載套件：

gcloud CLI：執行下列指令：

gcloud artifacts generic download \
  --project=cmoc-prod \
  --location=us \
  --repository=codemender-cli-production \
  --package=cm \
  --version=stable \
  --name=cm-linux-arm64.zip \
  --destination=./

curl：執行下列指令：

curl -L -o cm-linux-arm64.zip "https://artifactregistry.googleapis.com/download/v1/projects/cmoc-prod/locations/us/repositories/codemender-cli-production/files/cm%3Astable%3Acm-linux-arm64.zip:download?alt=media"

安裝 CLI：

unzip cm-linux-arm64.zip
chmod +x cm
sudo mv cm /usr/local/bin/cm

macOS Intel

如要下載及安裝 macOS (Intel) 專用的 CodeMender CLI，請按照下列步驟操作：

使用下列任一方法下載套件：

gcloud CLI：執行下列指令：

gcloud artifacts generic download \
  --project=cmoc-prod \
  --location=us \
  --repository=codemender-cli-production \
  --package=cm \
  --version=stable \
  --name=cm-darwin-amd64.zip \
  --destination=./

curl：執行下列指令：

curl -L -o cm-darwin-amd64.zip "https://artifactregistry.googleapis.com/download/v1/projects/cmoc-prod/locations/us/repositories/codemender-cli-production/files/cm%3Astable%3Acm-darwin-amd64.zip:download?alt=media"

安裝 CLI：

unzip cm-darwin-amd64.zip
chmod +x cm
mv cm /usr/local/bin/cm

macOS Apple 晶片

如要下載及安裝 macOS 專用的 CodeMender CLI (Apple 晶片)，請按照下列步驟操作：

使用下列任一方法下載套件：

gcloud CLI：執行下列指令：

gcloud artifacts generic download \
  --project=cmoc-prod \
  --location=us \
  --repository=codemender-cli-production \
  --package=cm \
  --version=stable \
  --name=cm-darwin-arm64.zip \
  --destination=./

curl：執行下列指令：

curl -L -o cm-darwin-arm64.zip "https://artifactregistry.googleapis.com/download/v1/projects/cmoc-prod/locations/us/repositories/codemender-cli-production/files/cm%3Astable%3Acm-darwin-arm64.zip:download?alt=media"

安裝 CLI：

unzip cm-darwin-arm64.zip
chmod +x cm
mv cm /usr/local/bin/cm

Windows x86_64

如要下載及安裝 Windows 版 (x86_64) CodeMender CLI，請按照下列步驟操作：

使用下列任一方法下載套件：

gcloud CLI：在 PowerShell 中執行下列指令：

gcloud artifacts generic download `
  --project=cmoc-prod `
  --location=us `
  --repository=codemender-cli-production `
  --package=cm `
  --version=stable `
  --name=cm-windows-amd64.zip `
  --destination=./

PowerShell：執行下列指令：

Invoke-WebRequest -Uri "https://artifactregistry.googleapis.com/download/v1/projects/cmoc-prod/locations/us/repositories/codemender-cli-production/files/cm%3Astable%3Acm-windows-amd64.zip:download?alt=media" -OutFile cm-windows-amd64.zip

安裝 CLI：

Expand-Archive -Path cm-windows-amd64.zip -DestinationPath ./
# Move cm.exe to a permanent folder and add it to your system PATH (e.g. Environmental Variables)

Windows ARM64

如要下載及安裝 Windows 專用的 CodeMender CLI (ARM64)：

使用下列任一方法下載套件：

gcloud CLI：在 PowerShell 中執行下列指令：

gcloud artifacts generic download `
  --project=cmoc-prod `
  --location=us `
  --repository=codemender-cli-production `
  --package=cm `
  --version=stable `
  --name=cm-windows-arm64.zip `
  --destination=./

PowerShell：執行下列指令：

Invoke-WebRequest -Uri "https://artifactregistry.googleapis.com/download/v1/projects/cmoc-prod/locations/us/repositories/codemender-cli-production/files/cm%3Astable%3Acm-windows-arm64.zip:download?alt=media" -OutFile cm-windows-arm64.zip

安裝 CLI：

Expand-Archive -Path cm-windows-arm64.zip -DestinationPath ./
# Move cm.exe to a permanent folder and add it to your system PATH (e.g. Environmental Variables)

設定 Google Cloud 憑證

由於 CodeMender CLI 會透過 Interactions API 與雲端代管的推論引擎互動，因此您必須在環境中設定 Google Cloud 應用程式預設憑證 (ADC)。

如要進行驗證，請執行下列指令，然後按照登入提示操作：

gcloud auth application-default login

初始化工作區

完成驗證後，下一步是在本機環境中初始化 CodeMender。初始化 CodeMender 會建立狀態追蹤檔案，並建立與雲端代管推論引擎的連線設定，藉此準備本機工作區。

從程式碼集的根目錄執行 cm init，建立本機狀態追蹤檔案並建立基準設定：

cm init

使用 --verify 旗標測試與雲端主控推論引擎的連線能力，並驗證工作區設定：

cm init --verify

設定參數 (`config.yaml`)

config.yaml的主要目標是根據本機系統的安全性、環境限制和效能需求，調整 CodeMender 代理的行為。

由於代管式 AI 代理程式會使用本機精靈用戶端執行本機指令 (例如建構程式碼、執行測試或編輯檔案)，因此這個設定檔會做為界線，定義代理程式可執行的動作。

用量

位置：根據預設，CLI 會從 ~/.codemender/config.yaml 讀取這個檔案。您可以設定 CM_HOME 環境變數 (例如 CM_HOME=/path/to/custom/dir，會讀取 /path/to/custom/dir/config.yaml)，覆寫工作區和設定目錄。
執行：執行 cm find、cm verify 或 cm fix 等指令時，本機用戶端會讀取這個檔案，設定安全參數、套用系統規避措施，並指定要忽略的檔案或目錄。

核心預設設定

以下說明核心預設參數的意義：

human_confirmation: true (或 require_confirmation: true)
- 意義：根據預設，CodeMender 無法修改磁碟上的任何檔案，或執行 Shell 命令，除非明確提示您在終端機中進行 [Y/n] 確認。
- 為何這是預設設定：CodeMender 可能會生成推測性修補程式，或嘗試執行攻擊指令碼來驗證安全漏洞。強制要求人工確認，有助於防止系統發生意外變更，或在本機環境中執行未經授權的程式碼。
- 略過：對於非互動式 CI/CD 管道，這項設定可以設為 false。
confirm_writes: false
- 意義：停用檔案修改的互動式提示，讓 CodeMender 代理程式直接將安全性修補程式寫入本機磁碟，並修改來源檔案，不必等待人工核准。
- 為什麼這是預設值：根據預設，CodeMender 會將這項安全防護機制設為 true，強制執行「人為介入」工作流程。由於 CodeMender 會對本機程式碼集採取行動，因此需要手動確認 (例如 Write? [Y/n])，可避免代理程式對來源檔案進行推測性、不正確或破壞性修改。只有在獨立、可拋棄式沙箱或自動化無頭 CI/CD 管道中執行時，才應將此值切換為 false。
include: [".py", ".java", ".go", ".js", ".jsx", ".mjs", ".cjs", ".ts", ".tsx", ".c", ".cc", ".cpp", ".cxx", ".h", ".hpp", ".cs", ".rs", ".kt", ".kts", ".rb", ".php"]
- 意義：定義明確的副檔名清單，授權 CodeMender 在掃描工作區時擷取及分析這些檔案。如果存放區中的檔案副檔名不在這個清單中，CodeMender 會自動略過。
- 為什麼這是預設設定：這份清單預設為主要程式設計語言，可盡量提高掃描效率，並避免代理程式將時間和權杖浪費在不相關的文字檔、建構構件或二進位檔。不過，由於現代應用程式通常會在部署設定或自動化工具中嵌入安全漏洞，因此您可以在 config.yaml 中手動擴充這個預設清單，加入設定檔、指令碼格式和 IaC 檔案 (例如 Shell 指令碼、XML、YAML、屬性和 JSON 檔案)，避免 CodeMender 默默忽略這些檔案。
exclude_dirs: ["node_modules", "vendor", "dist", "bin", "target", "obj", "build", ".gradle"]
- 意義：CodeMender 在掃描工作區和分析程式碼時，會完全略過這些目錄。
- 為什麼這是預設值：大型依附元件或建構資料夾會導致大量延遲和權杖懲罰。預設排除這些項目可確保高效能和快速回應時間。您可以在 config.yaml 中自訂這份清單，根據專案結構納入或排除特定目錄。
project_paths: []
- 說明：CodeMender 在執行工具時可存取 (讀取/寫入) 的目錄路徑清單。
- 為何這是預設值：預設為空白，這會將代理程式限制在掃描目標目錄中。如果建構或測試程序需要存取掃描目標目錄以外的檔案，請在此新增這些路徑。
- 構件目錄：代理程式也可以寫入每個工作階段的構件目錄 (~/.codemender/artifacts/<session_id>/ 或 $CM_HOME 下的對等項目)。
- 暫時檔案：啟用沙箱後，即使將 /tmp 新增至 project_paths，主機 /tmp 目錄一律會遭到封鎖。遵守 TMPDIR 的工具會改用構件目錄內的暫時目錄。
sandbox：
- 意義：程序層級沙箱環境的設定區塊。
- 子參數：
  - enabled: true：(布林值) 啟用或停用沙箱。如果將此項設為 true (預設值)，代理程式會在本地沙箱中執行工具。如果設為 false，代理程式會直接在主機系統上執行工具，不會隔離。
  - mounts：(物件)
    - target_dir: "."：(字串) 要在沙箱內掛接為有效工作區的目錄。CLI 會根據工作區根目錄解析相對路徑。
  - network：(物件)
    - profile: "permissive-closed"：(字串) 沙箱內的出站網路存取設定檔。目前不支援特定網域或網址模式的精細許可清單。支援的設定檔：
      - permissive-closed (預設)：完全隔離網路，沙箱會封鎖所有輸出連線。
      - permissive-open：允許完整的外送網路存取權。
security：
- 意義：安全性政策的設定區塊。
- 子參數：
  - protected_files: []：(字串清單) 要在沙箱內唯讀掛接的主機系統檔案或目錄，可防止修改 (例如 ["~/.ssh/*"])。支援路徑擴展 (~) 和萬用字元 (*)。
model: "gemini-3.8-flash"
- 意義：為後端推理迴圈提供支援的預設智慧引擎。
- 為何這是預設模型： gemini-3.8-flash 在速度、成本和分析推理方面取得最佳平衡，可建議修補程式。(如有需要，使用者可以覆寫這項設定，改用 gemini-3.1-pro 進行更深入、更複雜的推論)。
vcs: { type: "git" }
- 意義：透過 vcs 鍵定義專案使用的版本管控系統類型。如果未設定這項功能，工具會嘗試自動識別 Git 或 Mercurial 存放區。如果將 vcs 設為 none，CLI 會輸出警告，但會繼續執行，只是不含 VCS 功能。CodeMender 會根據這項設定管理推測性安全修正、追蹤程式碼集修改內容，以及與本機存放區整合。
- 為何這是預設設定：CodeMender 支援 Git、Mercurial 或自訂 VCS 設定。Git 是版本管控追蹤的業界標準，可確保差異整合順暢無礙，並安全地還原變更，因此是預設選項。
build: { command: "make build && make test" }
- 意義：定義 CodeMender 執行的確切殼層指令，用於編譯及建構專案，以及執行單元和迴歸測試。
- 為何這是預設值：設定建構和測試指令對於驗證工作流程至關重要。這項功能可讓 CodeMender 編譯專案，並在隔離的沙箱環境中執行現有的測試套件，證明產生的安全性修補程式能成功緩解安全漏洞，且不會破壞現有的應用程式邏輯。

執行沙箱

為保護工作站，避免檔案遭到非預期的修改，或工具產生非預期的副作用，CodeMender CLI 預設會在 OS 層級的沙箱中執行。您可以在設定中永久停用沙箱，也可以使用 CLI 標記，針對每個指令略過沙箱。

雖然這種沙箱機制可在工作站提供初步防禦層級，但與在完全隔離的虛擬機器 (VM) 中執行代理程式相比，安全性較弱：

Linux：使用核心命名空間 (CLONE_NEWNS、CLONE_NEWUSER 等) 和 seccomp 篩選器，隔離掛接點並限制系統呼叫。
macOS：使用內建的 sandbox-exec (Seatbelt) 機制。
Windows (實驗功能)：使用 AppContainer 隔離和存取控制清單 (ACL)。Windows 沙箱目前處於實驗階段，可能需要管理員權限，或與某些系統設定不相容。

沙箱行為

沙箱啟用後：

檔案系統隔離：代理程式只能讀取及寫入允許目錄中的檔案。沙箱會將這些目錄以外的任何寫入作業重新導向至暫時的記憶體內檔案系統 (tmpfs)，不會影響主機系統。
網路隔離：沙箱預設會封鎖對外網路存取權。這樣一來，代理程式 (或其叫用的建構工具) 就不會建立非預期的外部連線，或將資料傳輸到工作區外部。

建構和驗證期間的網路存取權

由於沙箱預設會啟用網路隔離 (sandbox.network.profile 預設為 permissive-closed)，因此代理程式在執行工具時無法存取網際網路。

這會對需要在建構或驗證步驟期間擷取外部依附元件的專案造成限制 (例如，在 build.command 中執行 npm install、pip install 或 go get)。如果建構程序嘗試存取外部網路服務，就會失敗。

處理網路依附元件

如果專案需要網路存取權才能建構或測試，您可以採取下列做法：

預先擷取依附元件：在主機系統上安裝所有必要依附元件，再執行 cm 指令，這樣建構指令就不需要網路存取權。
在沙箱中啟用網路存取權：變更 config.yaml 中的網路設定檔，允許對外連線：
```
sandbox:
  network:
    profile: "permissive-open"
```
注意：系統目前不支援特定網域或網址模式的精細許可清單 (例如只允許 npmjs.org)；permissive-open 會授予沙箱完整的輸出存取權。
略過沙箱：執行指令時加上 --unrestricted 旗標，即可停用沙箱，並完全略過該執行的檔案系統界線。

沙箱設定

你可以使用下列選項設定及控管沙箱：

持續性設定 (config.yaml)：您可以在 config.yaml 檔案中新增 sandbox、execution 和 security 區塊，自訂沙箱行為、檔案系統掛接、網路存取權和安全性政策。詳情請參閱「設定參數」。
使用 CLI (--sandbox) 控制沙箱：您可以將 --sandbox=true 或 --sandbox=false 傳遞至 cm find、cm verify 或 cm fix，明確啟用或停用單次執行的沙箱。
使用 CLI (--unrestricted) 略過隔離程序：您可以傳遞 --unrestricted 旗標，暫時略過單次執行的所有沙箱保護措施。這會停用檔案系統路徑界線 (允許代理程式存取主機上的任何路徑)，並完全停用 OS 層級的容器隔離 (包括網路隔離)。

選擇隔離等級

您可以根據安全需求和開發環境，選擇合適的隔離層級來執行 CodeMender CLI。

方法	說明	優點	缺點
內建沙箱 (作業系統層級)	這項功能預設為啟用，您可以在 `config.yaml` 檔案中停用，或使用 CLI 旗標略過。使用內建的 OS 功能 (命名空間/seccomp、`sandbox-exec`、`AppContainer` (實驗功能)) 隔離執行作業。	輕量級：啟動零負擔；可直接存取本機工作區工具，並進行精細控制。建議用於日常本機開發。	安全性取決於 OS 核心功能；隔離程度不如完整 VM；Windows 支援功能處於實驗階段，可能需要管理員權限，或與某些設定不相容。
容器	在容器 (例如 Docker) 中執行代理程式。	隔離效果良好；環境標準化。	需要容器執行階段；可能很耗資源；不允許直接與本機上的工具互動。
完整 VM	在專屬 VM 中執行代理程式。	最高安全性；完全隔離。	資源管理負擔高、啟動緩慢，且無法直接與本機上的工具互動。

遙測

為協助我們監控及改善產品健康狀態，我們會透過 CLI 收集匿名遙測資料。我們收集的所有資料 (包括基本使用情況指標和效能診斷) 都會完全去識別化。遙測功能絕不會收集或傳輸原始碼、檔案內容、發現項目、修補程式或使用者身分。

遙測功能預設為啟用。如要停用遙測功能，請將 CM_TELEMETRY_OPT_OUT 環境變數設為 1 或 true。

更新 CLI

CodeMender 內建更新機制，可確保您執行的是最新版本的 CLI。

自動檢查更新

根據預設，執行指令時，CodeMender CLI 會在背景自動檢查更新：

節流：為盡量減少負擔，自動檢查最多每 24 小時執行一次。
需要互動式終端機 (TTY)：CLI 只會在互動式終端機中執行時檢查更新，並提示您。在非互動式環境 (例如 CI/CD 管道或指令碼) 中，系統會略過檢查，且每天最多記錄一次警告訊息至 stderr。
提示：如有新版本，系統會在 stderr 上提示： none 🆕 A new CodeMender release is available: 1.1.0 Update now? (y/N): 選擇「是」y 或 yes 後，CodeMender 會下載更新、取代二進位檔，然後結束。您必須再次執行指令，才能使用新版本。如果選擇「否」，系統會略過更新並執行原始指令。
離線容許度：如果離線或無法連線至發布存放區，檢查會無聲無息地失敗，但 CodeMender 會繼續執行指令。
略過：您可以將 --yes 或 -y 旗標傳遞至任何指令，略過自動更新檢查。

手動更新 (`cm update`)

您可以執行 update 指令，強制 CodeMender 立即檢查及套用更新：

cm update

cm update 指令：

忽略 24 小時節流。
立即下載並套用更新，不會顯示提示 (非互動式)。
不需要互動式終端機 (適用於指令碼和設定管理)。

如果 CLI 安裝在需要提升權限的系統目錄中，請使用 sudo 執行更新：

sudo cm update

安裝及設定 CLI 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

架構和安全模式

環境設定

專案設定和 IAM 權限

必要 API

建議的預先定義 IAM 角色

下載並安裝 CodeMender CLI

Linux x86_64

Linux ARM64

macOS Intel

macOS Apple 晶片

Windows x86_64

Windows ARM64

設定 Google Cloud 憑證

初始化工作區

設定參數 (config.yaml)

用量

核心預設設定

執行沙箱

沙箱行為

建構和驗證期間的網路存取權

處理網路依附元件

沙箱設定

選擇隔離等級

遙測

更新 CLI

自動檢查更新

手動更新 (cm update)

安裝及設定 CLI

設定參數 (`config.yaml`)

手動更新 (`cm update`)