Kiro IDE 常見問題#

{
  "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 \"[你的中文提交資訊]\"。提交資訊應該清晰、簡潔，遵循良好的提交資訊規範，完全使用中文書寫。"
  }
}

# 錯誤資訊

「Shell 整合不可用」

# 嘗試自動修復

1. 按 Cmd/Ctrl+Shift+P 開啟命令面板
2. 執行 "Kiro: Enable Shell Integration"
3. 重新啟動 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 match -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)" }'
```

# 常見錯誤及解決方法

# 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
```

# 除錯方法

1. 開啟 Output → "Kiro - MCP Logs" 查看日誌
2. 透過 /mcp 命令檢查伺服器狀態
3. 手動執行伺服器命令進行測試

# 確認 .gitignore 的影響
cat .gitignore

# 確認 Kiro 的設定
{
  "fileFiltering": {
    "respectGitIgnore": false  # 暫時停用
  }
}

# 對於大檔案的情況
"@large-file.log:1000-2000"  # 指定行號範圍部分讀取

## 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](https://kiro.dev/docs/reference/auth-methods/)

---

## 3) 檢查回呼連接埠（重點：`localhost:3128`）

Kiro 登入會在本機起一個回呼監聽，常見是 **`http://127.0.0.1:3128`**；瀏覽器登入成功後會重新導向回這裡。若這個連接埠被佔用/被系統保留，瀏覽器就算開啟了也**回不來**，或者根本起不來登入流程。 [Hacker News](https://news.ycombinator.com/item?id=44562163&utm_source=chatgpt.com)[GitHub](https://github.com/kirodotdev/Kiro/issues/571)

看有沒有程式佔用 3128：

```sh
netstat -ano -p tcp | findstr :3128
```

- 如果看到 `LISTENING`/`ESTABLISHED`，記下 PID，在「工作管理員」結束它（或 `taskkill /PID <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 連接埠衝突/被系統保留**有關；釋放佔位或避免衝突即可恢復。[GitHub](https://github.com/kirodotdev/Kiro/issues/571)[Hacker News](https://news.ycombinator.com/item?id=44562163&utm_source=chatgpt.com)

> ⚠️ 如果你改動過系統動態連接埠範圍，請記錄原值；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\cache"
rmdir /S /Q "%LocalAppData%\Kiro"
```

> 這些是 Windows 上對應的本機狀態目錄；清理後常能恢復「卡住等待認證提供方」的問題。[Kiro](https://kiro.dev/docs/reference/troubleshooting/)

再啟動 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](https://docs.aws.amazon.com/singlesignon/latest/userguide/troubleshooting.html?utm_source=chatgpt.com)

---

## 6) 一鍵自檢腳本（PowerShell）

把下面內容貼到 **以系統管理員身分**執行的 PowerShell：

```batch
Write-Host "== Check default browser open =="
Start-Process "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 logging =="
$kiro = "$env:LocalAppData\Programs\Kiro\Kiro.exe"
if (Test-Path $kiro) {
  Start-Process $kiro -ArgumentList "--enable-logging"
} else {
  Write-Warning "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)

# 查看 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