WiseVine Tech BlogPublicationへの投稿
🍒

【Claude Code Web版】aqua/Taskfile環境構築でハマった6つのポイントと解決策

jkkitakita
に公開
Taskfile
aqua
Claude
Claude Code
tech

こんにちは。jkkitakitaです。
Claude Code Web版が今週リリースしましたね！
Claude Code Actions を用意すれば並列で実行できますが、Codex や Cursor みたいに気軽にクラウド環境で実行できればと思っていたので、
ぜひ使ってみよう！と思い、環境設定してみたのですが、地味にハマった&あまり記事になっていなさそうだったので、紹介しようと思います。

結論: 必要なドメインを許可し、hooks の SessionStart に開発環境セットアップのスクリプトを追加する

Claude Code 自体やリポジトリとの連携は完了していることを前提として
Claude Code Web版の画面、及び、対象リポジトリに下記設定をしました。

Claude Code Web版の画面

以下は私の例です。まず最小構成で通し、エラーが出たら段階的に追加してください。

許可されたドメイン一覧
api.anthropic.com
statsig.anthropic.com
claude.ai

github.com
www.github.com
api.github.com
raw.githubusercontent.com
objects.githubusercontent.com
codeload.github.com
avatars.githubusercontent.com
camo.githubusercontent.com
release-assets.githubusercontent.com

registry-1.docker.io
auth.docker.io
index.docker.io
hub.docker.com
www.docker.com

registry.npmjs.org
www.npmjs.com
www.npmjs.org
npmjs.com
npmjs.org
yarnpkg.com
registry.yarnpkg.com

pypi.org
www.pypi.org
files.pythonhosted.org
pythonhosted.org
test.pypi.org
pypi.python.org
pypa.io
www.pypa.io

tuf-repo-cdn.sigstore.dev
tuf-repo.github.com

releases.hashicorp.com
nodejs.org
awscli.amazonaws.com
tmaproduction.blob.core.windows.net

対象リポジトリ

対象リポジトリの各種設定ファイル、スクリプトを修正・追加しました。

.claude/settings.json の hooks
{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume|clear|compact",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/scripts/install_pkgs.sh",
            "timeout": 300
          }
        ]
      }
    ]
  }
}
開発環境セットアップのスクリプト（scripts/install_pkgs.sh）
#!/bin/bash
set -euo pipefail

# 例：リモート環境でのみ実行
if [ "$CLAUDE_CODE_REMOTE" != "true" ]; then
  exit 0
fi

# ref.
# * https://aquaproj.github.io/docs/products/aqua-installer/
# * https://github.com/aquaproj/aqua-installer/releases
AQUA_INSTALLER_VERSION="v4.0.3"
AQUA_INSTALLER_SHA256="d76bb5c3a23025e9d344aeba04c0a4d4ed6c9fb05e85530c8c3be2ef8e8f3a6a"
AQUA_INSTALLER_URL="https://raw.githubusercontent.com/aquaproj/aqua-installer/${AQUA_INSTALLER_VERSION}/aqua-installer"

have() { command -v "$1" >/dev/null 2>&1; }

# 既に aqua があるならインストール段取りはスキップ
if have aqua; then
  echo "[INFO] aqua is already installed: $(aqua -v || true)"
else
  echo "[INFO] Downloading aqua-installer ${AQUA_INSTALLER_VERSION} ..."
  curl -sSfL -O "${AQUA_INSTALLER_URL}"
  echo "[INFO] Verifying checksum ..."
  echo "${AQUA_INSTALLER_SHA256} aqua-installer" | sha256sum -c -
  chmod +x ./aqua-installer
  echo "[INFO] Running aqua-installer ..."
  ./aqua-installer
  rm -f ./aqua-installer
fi

AQUA_BIN="${AQUA_ROOT_DIR:-${XDG_DATA_HOME:-$HOME/.local/share}/aquaproj-aqua}/bin"
export PATH="${AQUA_BIN}:$PATH"
if [[ -n "$CLAUDE_ENV_FILE" ]]; then
  echo "export PATH=\"${AQUA_BIN}:\$PATH\"" >> "$CLAUDE_ENV_FILE"
fi

echo "[INFO] Running 'aqua install' ..."
aqua install
echo "[INFO] Running initial setup (this may take a few minutes)..."
task i
echo "[INFO] Generating API client code..."
task api:generate
echo "[INFO] Setup completed successfully!"

exit 0

今回試したリポジトリの aqua.yaml と Taskfile.yaml は以下の通りです。

aqua.yaml
---
registries:
  - type: standard
    ref: v4.427.0 # renovate: depName=aquaproj/aqua-registry
packages:
  # AWS関連
  - name: aws/aws-cli@2.31.14
  - name: aws/session-manager-plugin@1.2.707.0
  - name: theurichde/go-aws-sso@v1.5.0

  # GitHub Actions関連
  - name: rhysd/actionlint@v1.7.8
  - name: suzuki-shunsuke/ghalint@v1.5.3
  - name: suzuki-shunsuke/pinact@v3.4.2
  - name: suzuki-shunsuke/ghatm@v0.3.7

  # Terraform/IaC関連
  - name: hashicorp/terraform@v1.13.3
  - name: terraform-linters/tflint@v0.59.1
  - name: terraform-docs/terraform-docs@v0.20.0
  - name: suzuki-shunsuke/tfcmt@v4.14.12
  - name: getsops/sops@v3.11.0
  - name: suzuki-shunsuke/github-comment@v6.3.5

  # セキュリティ関連
  - name: aquasecurity/trivy@v0.67.2
  - name: secretlint/secretlint@v11.2.5
  - name: bridgecrewio/checkov@3.2.483

  # Docker関連
  - name: hadolint/hadolint@v2.14.0

  # Python関連
  - name: astral-sh/uv@0.9.2

  # Node.js関連
  - name: nodejs/node@v24.10.0

  # 開発ツール
  - name: evilmartians/lefthook@v1.13.6
  - name: pre-commit/pre-commit@v4.3.0
  - name: go-task/task@v3.45.4
  - name: cli/cli@v2.81.0
  - name: crate-ci/typos@v1.38.1
  - name: junegunn/fzf@v0.66.0
  - name: jqlang/jq@jq-1.8.1
Taskfile.yaml
# Taskfile.yaml
version: "3"

includes:
  backend:
    taskfile: ./backend/Taskfile.yml
    dir: ./backend
  frontend:
    taskfile: ./frontend/Taskfile.yml
    dir: ./frontend

tasks:
  default:
    desc: タスク一覧を表示
    cmd: task -l

  install:
    desc: 初期セットアップ
    run: once
    cmds:
      - task: aqua:install
      - task: npm:install:root
      - task: pre-commit:install
      - task: backend:install
      - task: frontend:install

  npm:install:root:
    desc: ルートのnpm依存関係をインストール（OpenAPI lint用）
    run: once
    internal: true
    preconditions:
      - sh: test -f package-lock.json
        msg: package-lock.json not found in root directory
    cmd: npm ci

  aqua:install:
    desc: aqua依存関係をインストール
    run: once
    internal: true
    cmd: aqua i

  pre-commit:install:
    desc: Git hooks セットアップ
    internal: true
    deps: [aqua:install]
    cmds:
      - lefthook install

  api:generate:
    desc: OpenAPI仕様からクライアントコード生成
    cmds:
      - task: backend:codegen
      - task: frontend:orval

# frontend/Taskfile.yaml
version: "3"

tasks:
  install:
    desc: npm依存関係をインストール
    cmds:
      - npm ci

  orval:
    desc: APIクライアントコード生成
    cmd: npm run orval

# backend/Taskfile.yaml
version: "3"

tasks:
  install:
    desc: バックエンドの依存関係インストール
    cmds:
      - uv sync --all-extras --locked

  codegen:
    desc: OpenAPI仕様からPydanticモデル生成
    cmd: |
      uv run datamodel-codegen \
        --input openapi/openapi.yaml \
        --input-file-type openapi \
        --output apps/common/generated/schemas.py \
        --output-model-type pydantic_v2.BaseModel \
        --use-subclass-enum \
        --use-standard-collections \
        --use-schema-description \
        --use-operation-id-as-name \
        --field-constraints \
        --collapse-root-models \
        --target-python-version 3.13 \
        --openapi-scopes schemas paths parameters

設定しているリポジトリ・ツールたち

  1. frontend(React・Vite), backend(Python・Django Ninja) ディレクトリがある monorepo の構成
  2. ツール等は、aqua で管理
  3. Taskfile をタスクランナーとして利用
  4. OpenAPI-First な開発で、orval と datamodel-code-generator を使って、フロントエンド、バックエンドのモデルや型定義、クライアントコード等の自動生成

セットアップ設定手順

設定手順としては、以下の通りです。

  1. .claude/settings.json と scripts/install_pkgs.sh を追加して、main ブランチに merge する
  2. Claude Code Web版の画面に遷移し、「環境を追加」を押下する

add-environment

  1. ネットワークアクセスを「カスタムアクセス」に変更し、「許可されたドメイン」に許可するドメインを追加し、「環境を作成」を押下する

allow-domains

  1. 作成した環境を選択して、あとは指示を出すだけ。

ハマりポイント

セットアップ設定手順はシンプルに書いていますが
結論に記載した設定に辿り着くまでに、いくつかハマりポイントがあったので紹介します。

1. デバッグが難しい

大前提として、echo でどこまでセットアップが進んでいるか出すようにしていますが、Claude Code の画面上には、この出力は表示されません。
冷静に記事を書いている今のタイミングだと、ローカルの .claude 配下のどこかのファイルを漁れば
SessionStart の時のログがどこかに残っているのかもしれませんが、そこまでできませんでした。
なので、毎回修正しては、main ブランチに merge して、試してを繰り返しました。

2. セットアップする際に必要なインターネットアクセスの特定

「1. デバッグが難しい」に関連してだが、何を許可すればいいのかわからない。
なので、トライアンドエラーを繰り返しました。
Claude Code Web版で、「aqua install 実行して」や「task install 実行して」と指示を出すと
下記のような Forbidden エラーが発生するので、そのエラー行からリクエスト先となる domain を抽出して
「許可されたドメイン」に追加する。というのを繰り返しました。

time=2025-10-23T10:40:15Z level=error msg=request failed env=linux/amd64 error=Get "https://nodejs.org/dist/v24.10.0/node-v24.10.0-linux-x64.tar.gz": Forbidden method=GET program=aqua program_version=2.55.0 url=https://nodejs.org/dist/v24.10.0/node-v24.10.0-linux-x64.tar.gz
error creating Sigstore verifier: failed to create TUF client: failed to load metadata: tuf refresh failed: Get "https://tuf-repo.github.com/4.root.json": Forbidden

ちなみに、許可しているドメインのベースは、デフォルト許可ドメイン に記載されている
Anthropic サービスやバージョン管理(GitHubのみ)、JavaScript/Node、Python などに加えて、以下も追加する必要がありました。

  • aqua-installer を github release からダウンロードするのに必要
    • release-assets.githubusercontent.com
  • aqua-installer の sha256sum で必要
    • tuf-repo-cdn.sigstore.dev、tuf-repo.github.com
  • terraform, nodejs, awscli を aqua で install するのに必要
    • releases.hashicorp.com、nodejs.org、awscli.amazonaws.com

3. Shebang は #!/usr/bin/env bash ではなく #!/bin/bash を使う

最初 AI で、ざっくり scripts/install_pkgs.sh を書かせた時に
Shebang が、#!/usr/bin/env bash となっていたのですが、
これだと /usr/bin/env: 'bash': No such file or directory のようなエラーが出てきて、そもそも起動に失敗していました。
最終的に公式ドキュメントの scripts/install_pkgs.sh と照らし合わせて、Shebang が原因だと判明し、修正しました。

# ❌
#!/usr/bin/env bash
# ⭕️
#!/bin/bash

4. PATH を通すのは、環境変数ではなく、CLAUDE_ENV_FILE に書き込む

これは、ドキュメントをしっかり読めば分かる内容なのですが、aqua の PATH を通すのに少し手こずりました。
以下のようなことを試しましたが、全てうまくいきませんでした。

  1. Claude Code Web版 の environment の環境変数に PATH=$HOME/.local/share/aquaproj-aqua/bin:$PATH を追加
  2. .claude/settings.json の env に　"PATH": "$HOME/.local/share/aquaproj-aqua/bin:$PATH" を追加
  3. scripts/install_pkgs.sh の中で、.bashrc などに追加

などなど。

環境変数の永続化 ってところにCLAUDE_ENV_FILE に追加すればいいよ。との記載があったので、それでいけました。
ちなみに、export も必要でした。

# ❌
echo "PATH=\"${AQUA_BIN}:\$PATH\"" >> "$CLAUDE_ENV_FILE"
# ⭕️
echo "export PATH=\"${AQUA_BIN}:\$PATH\"" >> "$CLAUDE_ENV_FILE"

5. ローカル環境では scripts/install_pkgs.sh を実行しないようにする

CLAUDE_CODE_REMOTE が true の場合のみ実行されるように
scripts/install_pkgs.sh の最初に下記条件分岐を追加して、exit 0 する必要があります。
これをやらないと、ローカルで、claude コマンドを実行した時も動いてしまって、起動が遅くなります。

# 例：リモート環境でのみ実行
if [ "$CLAUDE_CODE_REMOTE" != "true" ]; then
  exit 0
fi

6. SessionStart が timeout(60s) していた

最後に、これもすぐには分からなかったのですが、
「ls -la $HOME/.local/share/aquaproj-aqua/bin 実行して」
と指示を出すと、aqua install でツール等はインストールされているようなのですが、
npm ci や uv sync が実行されていない状態でした（task install が実行されていない）。
スクリプト的には問題ないはずなので、timeout あたりが怪しいと思い、
timeout のデフォルトは、60s のようなので、
とりあえず 300s に伸ばしたら、無事うまくいきました🎉

さいごに

Claude Code Web版については、Claude Code Web版 - スマホで指示、帰宅後に完成する開発の未来 や Claude Skills × GitHub Actions でバグ修正の自動化を試す！ の中でも紹介されていて、
並列実行もできるし、MCP もクラウド環境で設定できるし（GitHub Codespaces だとクラウド環境では MCP を活用できない気がします）、テレポートもできて良さそうだと思ってセットアップしていたのですが、
思ったより時間がかかってしまい、せっかくなので記事にしてみました。
今回色々ハマりましたが、まだリサーチプレビュー版なので、これからこの辺りも改善していってくれることを期待しています！
どなたかの参考になれば幸いです！🙇

GitHubで編集を提案
WiseVine Tech Blog
WiseVine Tech BlogPublication

株式会社WiseVineは「未来の世代に豊かな世界を残す」というミッションをもとに、行政向け経営管理SaaS「WiseVine Build&Scrap」を開発・提供をしています。

Discussion