IDE 常見錯誤及解決方案
全部開啟這兩個選項需要在設定中啟用 Codebase Indexing 才能啟動。但是需要注意：啟用 Codebase Indexing 後可能會導致 CPU/記憶體佔用過高。
在 Agentic Coding 時代，基於 Local RAG 的 Codebase indexing 不再是必選項，它會消耗額外效能（CPU 和記憶體），召回效果不穩定，並且可以使用 fs_search tool 或類似的 CLI 替代，甚至效果更好。所以並不建議使用。
建議的 workaround：
- 直接透過聊天告訴 AI「在程式碼庫中搜尋 XXX」，利用 fs_search tool 進行搜尋
- 使用 ast-grep 等專用 CLI 工具實現相關程式碼搜尋
此問題在 GitHub Issue 中有追蹤。
暫時的解決方案是：使用 Ctrl+L 後，在輸入框敲一個空格就可以輸入中文了。
v0.5.0 版本以後，Kiro 會自動在 Ctrl+L 後新增一個空格，此時可以輸入中文。但是如果使用者刪除了這個空格，就要手動新增空格了。
報錯： Improperly formed request 或 An unexpected error occurred
通常是 MCP Tool 的描述格式不規範，特別是 input_schema 欄位，需要嚴格保證為合法的 JSON Schema。請檢查您的 MCP Server 是否為最新版本。
預設情況下 Kiro 的自動程式碼補全就是啟用的狀態。可以點擊底部欄的 Autocomplete 按鈕來查看和修改自動補全的設定。
目前在版本管理介面的 🪄 按鈕無法自訂語言，只能產生英文，也不會受到 Steering 檔案影響。
緩解的方案是：透過聊天面板，告訴 Kiro：「提交當前修改，使用中文 Commit Message」，讓 Kiro 透過 git 命令列實現提交。
為了讓使用更加絲滑，您可以建立一個手動觸發的 Agent Hooks，參考內容（.kiro\hooks\manual-git-commit.kiro.hook）：
{
"enabled": true,
"name": "Git提交",
"description": "手動觸發的鉤子，用於將當前修改提交到Git，使用中文提交訊息",
"version": "1",
"when": {
"type": "userTriggered"
},
"then": {
"type": "askAgent",
"prompt": "查看當前的git修改，使用git status和git diff命令。建立一個有意義的中文提交訊息來描述這些修改。然後執行：git add -A && git commit -m \"[你的中文提交訊息]\"。提交訊息應該清楚、簡潔，遵循良好的提交訊息規範，完全使用中文書寫。"
}
}
這樣，當需要提交的時候，點擊觸發 Agent Hook 即可。
更新 Kiro
打開命令面板 (Cmd+Shift+P)，輸入“Kiro: Check for Updates”，並在更新後重新啓動 Kiro。
# 錯誤信息
"Kiro 已損壞，無法打開。你應該將它移到廢紙簍。" / "Kiro is damaged and can't be opened. You should move it to the Trash"
# 原因
macOS 的 Gatekeeper 誤報導致
# 解決方法（按簡單順序嘗試）
# 方法 1：通過系統設置授權
1. 打開「系統設置」→「隱私與安全性」
2. 在提示「無法確認開發者身份的 Kiro」旁點擊「仍然允許」
3. 重新打開 Kiro
# 方法 2：移動文件重置
1. 將 Kiro.app 拖到桌面
2. 再從桌面拖回「應用程序」文件夾
3. 嘗試打開
# 方法 3：通過命令行刪除屬性
```bash
sudo xattr -d com.apple.quarantine /Applications/Kiro.app
...
Timed out waiting for authentication provider ‘Kiro’ to register
參考下文登錄退出異常，排查系統瀏覽器是否可以被正常喚起，以及回調端口是否被佔用
Kiro access not available for this account
- 如果使用個人賬號（GitHub / Google / AWS Builder ID），請確保已獲得激活碼激活賬號。在 Kiro 預覽階段，AWS Builder ID 不需要激活碼即可進入應用，但是需要付費訂閱纔可以正常使用。
- 如果使用企業賬號，使用 Identity Center 進行登錄，請確認是否用戶是通過【組】進行訂閱，如果是通過【組】進行訂閱，則需要等待最長 24 小時的激活時間。
編輯文件失敗
原理: Agent 在編輯文件時會先搜索一個 模式，然後替換它爲新的代碼塊。如果這個 模式 在文件中有多個匹配或者沒有匹配，agent 就會無法替換代碼塊從而報錯。
**通常導致這些問題的原因包括：**
1. 文件被人類或其他工具修改後沒有被 AI 重新讀取
2. 文件太長，導致簡單的 模式 在同一個文件中出現多次
3. 需要搜索的 模式 過於複雜或存在特殊字符，導致 LLM 生成的 搜尋 模式 不合法或不存在
4. LLM 自身的幻覺導致 搜尋 模式 不存在或格式錯誤
緩解方式:
1. 告訴 AI 使用 Shell 命令或腳本進行文件編輯
2. 讓 AI 生成正確的或更加準確的搜索 模式 後重試
3. 讓 AI 說出它的思路，人工編輯文件
無法使用 Shell 集成
“Shell 集成不可用”
- 按 Cmd/Ctrl+Shift+P 打開命令面板
- 執行 “Kiro: Enable Shell Integration”
- 重啓 Kiro
#手動修復方法
‘’’sh
# Zsh（macOS 默認）
echo '[["$TERM_PROGRAM" == "kiro"]] && . "$(Kiro --locate-Shell-integration-path zsh)"' >> ~/.zshrc
source ~/.zshrc
# Bash
echo '[["$TERM_PROGRAM" == "kiro"]] && . "$(Kiro --locate-Shell-integration-path bash)"' >> ~/.bashrc
source ~/.bashrc
# Fish
echo 'string 匹配 -q "$TERM_PROGRAM" "Kiro"' >> ~/.config/fish/config.fish
echo 'and . (Kiro --locate-Shell-integration-path fish)' >> ~/.config/fish/config.fis
# PowerShell（Windows）
Add-Content $PROFILE 'if ($env:TERM_PROGRAM -eq "Kiro") { . "$(Kiro --locate-Shell-integration-path pwsh)" }'
...
認證錯誤（IAM Identity Center）
- 沒有 Q Developer Pro 訂閱 → 請使用 Builder ID 或社交賬號登錄
- 區域設置錯誤 → 請確認公司使用的 IAM Identity Center 的區域（不是 Amazon Q Developer 訂閱的區域）。
- Start URL 錯誤 → 請聯絡 IT 部門確認正確的 URL。範例：https://your-company.awsapps.com/start
MCP 服務器連接錯誤
# 常見錯誤及解決方法
# Error: Command not found
→ 未安裝必要的工具
# 針對 AWS Docs Server
‘’’sh
curl -LsSf https://astral.sh/uv/install.sh | sh
uv Python install 3.10
# 針對 Error: Timeout
→ 增加超時時間 “timeout”: 30000 # 30 秒
# 針對 Error: Permission denied
→ 檢查 API 密鑰和認證信息
‘’’sh
echo $GITHUB_TOKEN
echo $BRAVE_API_KEY
...
# 調試方法
- 打開 Output → “Kiro - MCP Logs” 查看日誌
- 通過 /mcp 命令檢查服務器狀態
- 手動執行服務器命令進行測試
文件未找到或無法讀取
# 確認 .gitignore 的影響
cat .gitignore
# 確認 Kiro 的配置
{ “fileFiltering”: { “respectGitIgnore”: false # 臨時禁用
}
}
# 對於大文件的情況
“@large-file.log:1000-2000” # 指定行號範圍部分讀取
登錄退出異常
以下是 Windows 環境排查登錄退出異常的方法，Mac/Linux 用戶可以參考流程。
## 1) 先用“官方建議”的方式打開日誌
1. 以管理員打開 命令提示符（CMD）。
2. 運行（按你的安裝路徑替換）：
‘’’sh
"%LocalAppData%\Programs\Kiro\Kiro.exe" --enable-logging
...
>這是 Kiro 文檔給 Windows 的排查方式，能看到認證時的錯誤信息（比如權限或回調失敗）。 [Kiro](https://kiro.dev/docs/reference/troubleshooting/)
---
## 2) 快速自檢：默認瀏覽器能否被系統調用
在同一個 CMD 裏試：
‘’’ sh
start "" "https://example.com"
...
-能打開：默認瀏覽器關聯正常。
-打不開：去 設置 → 應用 → 默認應用，把 HTTPS 關聯到 Edge/Chrome，然後再試一次。
> Kiro 登錄會“把你帶到默認瀏覽器完成驗證”。如果系統層面打不開瀏覽器，Kiro 自然不會彈。Kiro
## 3) 檢查回調端口（重點：localhost:3128）
Kiro 登錄會在本地起一個回調監聽，常見是 http://127.0.0.1:3128；瀏覽器登錄成功後會重定向回這裏。若這個端口被佔用/被系統保留，瀏覽器就算打開了也回不來，或者根本起不來登錄流程。 Hacker NewsGitHub
看有沒有程序佔用 3128：
‘’’ sh
netstat -ano -p tcp | findstr :3128
...
-如果看到 LISTENING/ESTABLISHED，記下 PID，在“任務管理器”結束它（或 taskkill /PID /F）。
- 常見佔用者：代理/抓包工具（Fiddler、CNTLM、Zscaler 等）。
看 3128 是否被 Windows 保留爲排除端口（Excluded Port Range）：
‘’’ sh
netsh int ipv4 show excludedportrange protocol=tcp
...
-如果輸出範圍裏包含 3128，則該端口不可綁定，Kiro 無法啓動回調服務（這會導致“打不開瀏覽器/卡登錄”）。
釋放 3128 的排除佔位（需要管理員 CMD，謹慎執行）：
‘’’ sh
netsh int ipv4 delete excludedportrange protocol=tcp startport=3128 numberofports=1
> 有用戶在 Windows 上遇到“登錄不彈/不回跳”，確認與 3128 端口衝突/被系統保留有關；釋放佔位或避免衝突即可恢復。GitHubHacker News
> ⚠️ 如果你改動過系統動態端口範圍，請記錄原值；Windows 默認動態端口一般爲 start=49152 num=16384，可用
> ‘netsh int ipv4 show dynamicport tcp 查看，必要時用
> ‘netsh int ipv4 set dynamicport tcp start=49152 num=16384 恢復。
---
## 4) 清理“對登錄有影響”的緩存
### Windows
先完全退出 Kiro（或 ‘taskkill /IM Kiro.exe /F’），然後刪除：
‘’’ sh
rmdir /S /Q "%AppData%\Kiro"
rmdir /S /Q "%UserProfile%\.Kiro"
rmdir /S /Q "%UserProfile%\.AWS\sso\快取"
rmdir /S /Q "%LocalAppData%\Kiro"
...
> 這些是 Windows 上對應的本地狀態目錄；清理後常能恢復“卡住等待認證提供方”的問題。Kiro
再啓動 Kiro 重試登錄。
### MacOS
rm ~/.aws/sso/cache/kiro-auth-token.json
再啓動 Kiro 重試登錄。
---
## 5) 如果你用的是 IAM Identity Center 登錄
- **必須有 Q Developer Pro 訂閱纔可用 Identity Center 登錄方式；否則會報“簽入錯誤”。[Kiro] (https://kiro.dev/docs/reference/troubleshooting/)
- Kiro 目前 **默認使用 us-east-1**做 Identity Center 登錄；如果你的目錄/配置在別的 Region，會導致無法登錄。此時可暫時改用 **Builder ID / GitHub / Google** 登錄，或把目錄配到該 Region。 [Kiro](https://kiro.dev/docs/reference/troubleshooting/)
- IAM Identity Center 的常見登錄/會話問題可參考官方故障排查。AWS 文檔+1
## 6) 一鍵自檢腳本（PowerShell）
把下面內容粘到 **以管理員身份**運行的 PowerShell：
```batch
Write-Host "== Check default browser open =="
Start-程序 "https://example.com"
Write-Host "`n== Check port 3128 usage =="
netstat -ano -p tcp | Select-String ":3128"
Write-Host "`n== Check excluded port ranges (tcp) =="
netsh int ipv4 show excludedportrange protocol=tcp
Write-Host "`n== Launch Kiro with 日誌記錄 =="
$kiro = "$env:LocalAppData\Programs\Kiro\Kiro.exe"
if (測試-Path $Kiro) {
Start-程序 $Kiro -ArgumentList "--enable-日誌記錄"
} else {
Write-警告 "Kiro.exe not found at $Kiro"
}
...
---
### 成功後的驗證
-瀏覽器彈出後，完成授權應自動回到 Kiro；若瀏覽器地址欄出現 http://127.0.0.1:3128/...，說明回調端口正常。 [Hacker News](https://news.ycombinator.com/item?id=44562163&utm_source=chatgpt.com)
請首先確認登入時 StartURL 和 Region 是否選擇正確。如有需要，請聯絡您的管理員獲取正確的 StartURL 和 Region。
如果報錯訊息是：「有些內容無法計算：我們無法驗證您的登入憑證，請重試」，說明您的使用者名稱或密碼填寫有誤。
如果上述資訊無誤，請檢查您的系統時間是否正確。
請刪除此檔案：~/.aws/sso/cache/kiro-auth-token.json
通常是由於 LLM 的幻覺導致，可以告訴 AI「重試」或者「繼續」或者「go on」，如果多次重試仍然失敗，可以嘗試重新開始對話。
通常是網路不穩定導致，可以告訴 AI「重試」或者「繼續」或者「go on」，如果多次重試仍然失敗，可以嘗試重新開始對話，或排查網路連線。
通常是網路不穩定導致，可以告訴 AI「重試」或者「繼續」或者「go on」，如果多次重試仍然失敗，可以嘗試重新開始對話，或排查網路連線。
如果您使用 IAM Identity Center 進行登入，您可以在 IAM Identity Center 中設定工作階段有效時間為 90 天，來避免頻繁登入。參考官方文件。
進階除錯技巧
全部開啟#查看 Kiro 各服務的日誌
View -> Output
#啟用 Kiro 日誌
kiro --enable-logging
#開啟開發者工具
Help → Toggle Developer Tools → Console
#查看當前設定
cat ~/.kiro/settings.json
cat .kiro/settings.json
#查看記憶體（上下文）內容
/memory show
#手動測試 MCP 伺服器
#以 GitHub 伺服器為例
npx @modelcontextprotocol/server-github
#檢查網路問題
curl -I https://api.github.com
curl -I https://kiro.dev
清除本地檔案
全部開啟如果以上方法無法使 Kiro 正常工作，也可以嘗試徹底清除本地檔案後重新安裝 Kiro。
Windows
- 停止所有正在執行的 Kiro 處理程序
- taskkill /f /im Kiro.exe
- 解除安裝（如果使用的是使用者級安裝）
- rmdir /s /q "%LOCALAPPDATA%\Programs\kiro"
- 解除安裝（如果使用的是系統級安裝）
- if exist "%PROGRAMFILES%\kiro" rmdir /s /q "%PROGRAMFILES%\kiro"
- 刪除所有使用者資料和設定
- rmdir /s /q "%APPDATA%\Kiro"
- 刪除外掛程式
- rmdir /s /q "%USERPROFILE%.kiro"
- 從 Program Files (x86) 中刪除
- if exist "%PROGRAMFILES(X86)%\kiro" rmdir /s /q "%PROGRAMFILES(X86)%\kiro"
- 從桌面圖示和開始選單中刪除
- if exist "%USERPROFILE%\Desktop\kiro.lnk" del /q "%USERPROFILE%\Desktop\kiro.lnk"
- if exist "%APPDATA%\Microsoft\Windows\Start Menu\Programs\kiro" rmdir /s /q "%APPDATA%\Microsoft\Windows\Start Menu\Programs\kiro"
MacOS
- 刪除 ~/.kiro
- 刪除 Library/Application Support/Kiro
CLI 常見錯誤
全部開啟執行 MCP Tool 時報錯
報錯： Improperly formed request 或 An unexpected error occurred
通常是 MCP Tool 的描述格式不規範，特別是 input_schema 欄位，需要嚴格保證為合法的 JSON Schema。
可以使用 /tools schema 子命令查看 MCP Tool 的描述，確認 input_schema 欄位是否合法。
使用蘋果原生 Terminal 時崩潰
建議使用 iTerm2 作為 Terminal 來使用 Kiro CLI。
如果需要排查崩潰原因，可以嘗試使用此指令碼收集 Terminal 日誌後交給 Kiro CLI 來排查。
如何還原預設 Agent
使用 Kiro CLI 時，如果透過 /agent set-default --name 設定的預設 Agent 後，希望恢復預設的 Agent，可以使用命令 kiro-cli settings --delete chat.defaultAgent 刪除設定來還原預設 Agent。
無法升級
設定 VPC Endpoint 後，可能無法使用 kiro-cli update 進行 CLI 的升級。這是因為升級時需要存取 desktop-release.q.us-east-1.amazonaws.com，它是 Q 的 VPC Endpoint 的子網域名稱。如果您需要升級，可以參考此文件，從公網下載 zip 安裝套件後手動安裝。
byte index is not a char boundary
Kiro CLI 使用 Rust 語言編寫，對 UTF-8 字串的合法性有嚴格要求。此報錯說明 Kiro CLI 處理了非法的 UTF-8 字串，請檢查本地檔案是否包含非法 UTF-8 字元。
Prompt 如何定義和傳遞參數
目前只有 MCP Prompt 支援參數。可以使用 shinkuro 或類似的 MCP 伺服器，把檔案提示詞轉為 MCP 提示詞，從而支援參數。
使用者管理
全部開啟如何使用 API 實現訂閱或批次訂閱？
目前 Kiro 並沒有公開 API/SDK，但是有社群方案透過手動建構 SigV4 簽章的方式實現了批次訂閱（或基於 API 自動訂閱），詳見此 GitHub Repo。
IDE 問題上報
如果是偶發性的問題（例如，AI 幻覺、命令參數不正確）是正常現象。如果 Kiro 在某個問題上能穩定復現，建議獲取 Logs 提供給 AWS Support 或者 AWS 解決方案架構師。
日誌獲取方式：
- 開啟 Kiro 的 OUTPUT。透過點擊選單列的 View，再點擊 Output 開啟面板
- 下拉選擇 Kiro 相關的日誌，如 Kiro Logs。您可以看下哪個日誌裡面有報錯
- 點擊齒輪按鈕，選擇 Trace 類型的日誌
- 可以點擊選項按鈕，在編輯器中開啟日誌以便複製和儲存
除了上述 OUTPUT 面板中的日誌，還可以嘗試查看頁面日誌。頂部列點擊 Help -> Toggle Developer Tools 即可開啟開發者工具，點擊其中的 Console 面板即可查看日誌。
日誌收集完畢後，點擊 Kiro 底部列的「Report issue」按鈕進行問題上報。
如何查看 Kiro CLI 日誌
最新版本 Kiro CLI 可以使用 /logdump 命令把日誌儲存為一個 ZIP 檔案。
我有 Kiro CLI 問題希望上報給產品團隊，請問需要提供哪些資訊？
為加速我們排查您遇到的問題，我們建議您復現問題，並提供如下資訊給 AWS Support 或者 AWS 解決方案架構師：
必須項：
- 日誌資訊（建議去除敏感資訊）。請參考上文獲取 CLI 的日誌
- CLI 的版本資訊，使用 kiro-cli --version 可以查看當前版本。如果不是最新版，您可以嘗試執行 kiro-cli update 升級到最新版後，再看下問題是否還存在
- 作業系統版本資訊，如 Windows 11
- 問題描述，以及已經進行過哪些排查
可選項：
- 問題的影片或者截圖（如您能提供問題的影片或者截圖將有助於我們排查問題）