使用说明

Pincer操作

GitOps驱动的Kubernetes平台，用于部署和操作龙虾 --开源、自托管的AI代理运行时。将OpenClaw作为具有K8s本机安全性（NetworkPolicy、securityContext、Pod安全标准）的独立StatefulSet运行。此存储库是 单一事实来源 对于集群状态。

今后的工作： 我们正在评估 OpenShell 沙盒隔离和尼莫爪内核级隔离的参考架构（Landlock、seccomp BPF、网络命名空间）。这些尚未集成——有关更新，请参阅项目路线图。

建筑

Kinder or KIND multi-node (1 control-plane + 2 workers)
  → [Kinder: built-in MetalLB, Envoy GW controller, cert-manager]
  → [KIND: ArgoCD-managed MetalLB, Envoy GW controller, cert-manager]
    → Envoy Gateway DaemonSet + hostPort (ArgoCD-managed, both providers)
      → ArgoCD (App of Apps pattern, self-managing)
        → OpenClaw Gateway (StatefulSet, single replica, PVC-backed)

所有内容都通过ArgoCD同步波从单个根应用程序部署：

波形	组件	目的
-10	ArgoCD自我管理	在管理其他任何事情之前必须存在
-5	MetalLB	网关所需的负载均衡器IP
-4	Envoy网关控制器	网关API CRD和控制器
-3	密封的秘密	在工作负载需要之前解密密封的秘密
-2	证书管理器	TLS证书基础结构
-1	Envoy网关配置	网关+HTTPRoute资源（需要-4的CRD）
+10	OpenClaw网关	PVC支持存储的AI代理运行时

使用Kinder（默认）时，跳过waves-5（MetalLB）、-4（Envoy网关控制器）和-2（证书管理器）——这些组件由Kinder作为内置插件提供。

快速开始

先决条件

Docker 桌面版
更友好的（默认）或亲切 v0.20+
kubectl 的
kubeseal （用于秘密管理）
ArgoCD命令行界面（用于同步操作和状态检查）
Kubeconform （用于舱单验证）
蝙蝠（用于运行测试）

克隆后

make hooks    # Install git pre-commit hooks

您可以通过以下方式验证挂钩是否已安装：

test -x .git/hooks/pre-commit && echo "installed" || echo "not installed"

独自创立

make up                    # Bootstrap with Kinder (default)
CLUSTER_PROVIDER=kind make up  # Bootstrap with KIND instead

这将创建一个3节点集群（1个控制平面+2个工作节点），安装ArgoCD，并部署整个堆栈。Kinder、MetalLB、Envoy网关控制器和证书管理器作为内置插件提供；借助KIND，所有基础设施均由ArgoCD管理。Idempotent——多次跑步是安全的。

引导完成后（约4分钟），可以在以下网址访问OpenClaw http://localhost.

供应商差异

	Kinder（默认）	KIND（选择加入）
MetalLB	内置插件	ArgoCD管理
Envoy网关控制器	内置插件	ArgoCD管理
证书管理器	内置插件	ArgoCD管理
Envoy DaemonSet+hostPort	ArgoCD管理	ArgoCD管理
密封的秘密	ArgoCD管理	ArgoCD管理
OpenClaw	ArgoCD管理	ArgoCD管理
Bootstrap步骤	更少（跳过插件基础架构）	完整的v1.0流程

两个提供者都产生相同的集群拓扑（1个控制平面+2个worker），OpenClaw可在以下网址访问 http://localhost 在bootstrap之后。

部署后设置

集群运行后，通过其CLI配置OpenClaw：

# 1. Run the onboarding wizard (configures LLM provider keys, gateway settings)
make openclaw-onboard

# 2. Open the authenticated dashboard (extracts token and opens browser)
make openclaw-dashboard

# 3. Click "Connect" in the dashboard, then approve the device pairing request
make openclaw-cli CMD="devices list"
make openclaw-cli CMD="devices approve <requestId>"

# 4. Click "Connect" again — status should go Online

LLM提供者密钥（Anthropic、OpenAI等）在入职期间配置并存储在PVC上——它们是不在部署清单或K8s机密中设置。

管理渠道和设备

make openclaw-channels                                           # List configured channels
make openclaw-cli CMD="channels login"                           # WhatsApp QR login
make openclaw-cli CMD="channels add --channel telegram --token YOUR_TOKEN"
make openclaw-cli CMD="channels add --channel discord --token YOUR_TOKEN"

make openclaw-devices                                            # List paired devices
make openclaw-cli CMD="devices approve <requestId>"              # Approve a device

跑 make openclaw-cli 无需参数即可查看所有可用命令。

拆除

make down     # Destroy the cluster (sealing keys preserved at ~/.pincer/)
make clean    # Destroy cluster + remove Docker network and backups
make reset    # Full teardown + rebuild from scratch

生成文件目标

跑 make 或 make help 查看所有目标：

目标	描述
生命周期
`make up`	创建集群并部署所有内容（幂等）
`make up-verbose`	带有详细输出的Bootstrap
`make down`	销毁集群（保留密封密钥）
`make clean`	销毁集群+删除Docker网络和备份
`make reset`	完全重置：拆解-清理然后引导
发展
`make hooks`	安装git预提交钩子
`make validate`	验证所有Kubernetes清单（kubeconform）
`make test`	运行所有BATS测试（单元+集成）
`make test-unit`	仅运行单元测试
`make test-integration`	仅运行集成测试
`make check`	运行验证+所有测试
运营
`make doctor`	检查当前提供程序的群集运行状况
`make status`	显示ArgoCD应用程序同步状态
`make sync`	同步所有ArgoCD应用程序
`make password`	打印ArgoCD管理员密码
`make port-forward`	端口转发到ArgoCD UI（本地主机：8080）
`make setup-mcp`	为MCP集成生成ArgoCD API令牌
`make verify-netpol`	运行运行时NetworkPolicy强制测试
`make load-image IMAGE=name:tag`	将本地图像加载到KIND中
`make seal FILE=secret.yaml`	使用kubeseal加密秘密
`make logs`	尾部OpenClaw网关日志
`make pods`	列出命名空间中的所有Pod
`make version`	显示集群和工具版本
OpenClaw命令行界面
`make openclaw-onboard`	运行入职向导（交互式）
`make openclaw-dashboard`	显示仪表板信息
`make openclaw-channels`	列出已配置的频道
`make openclaw-devices`	列出配对设备
`make openclaw-health`	HTTP健康检查
`make openclaw-shell`	OpenClaw pod中的交互式shell
`make openclaw-cli CMD="..."`	运行任何OpenClaw CLI命令

仓库结构

pincer-ops/
├── Makefile                          # Developer workflow (make help)
├── bootstrap/
│   ├── kind/                         # KIND-specific ArgoCD Applications
│   │   ├── root-app.yaml             # Root Application (includes all infra)
│   │   ├── infra-*.yaml              # Infrastructure Applications (all components)
│   │   └── workload-openclaw.yaml    # OpenClaw Application
│   ├── kinder/                       # Kinder-specific ArgoCD Applications
│   │   ├── root-app.yaml             # Root Application (excludes Kinder-provided infra)
│   │   ├── infra-*.yaml              # Kinder-compatible infrastructure Applications
│   │   └── workload-openclaw.yaml    # OpenClaw Application
├── infrastructure/
│   ├── metallb/                      # MetalLB L2 LoadBalancer
│   ├── envoy-gateway/                # Gateway API implementation
│   ├── sealed-secrets/               # Bitnami Sealed Secrets controller
│   └── cert-manager/                 # TLS certificate management
├── workloads/
│   └── openclaw/
│       ├── base/                     # StatefulSet, Service, ConfigMap, HTTPRoute, NetworkPolicy
│       └── overlays/dev/             # Kustomize dev overlay
├── cluster/
│   ├── kind-config.yaml              # KIND cluster definition (3 nodes)
│   └── kinder-config.yaml            # Kinder cluster definition (3 nodes + addons)
├── scripts/
│   ├── bootstrap.sh                  # Full cluster creation + deployment
│   ├── teardown.sh                   # Cluster destruction
│   ├── setup-mcp.sh                  # MCP server configuration for Claude Code
│   ├── validate-manifests.sh         # CI manifest validation (kubeconform)
│   ├── verify-networkpolicy.sh       # Runtime NetworkPolicy enforcement tests
│   ├── run-tests.sh                  # BATS test runner
│   ├── lib/common.sh                 # Shared helper library
│   ├── lib/sealed-secrets.sh         # Sealing key backup/restore
│   └── hooks/                        # Pre-commit hook for plaintext Secret detection
└── tests/
    ├── test_helper.bash              # Common BATS test infrastructure
    ├── unit/                         # Unit tests (107 tests)
    └── integration/                  # Integration tests (10 tests)

核心不变

kubectl apply -f bootstrap/kinder/root-app.yaml   # Kinder (default)
kubectl apply -f bootstrap/kind/root-app.yaml     # KIND

此单个命令必须重建所选提供程序的完整群集状态。此存储库中的每个资源要么是根应用程序，要么是ArgoCD可以通过它发现的。

关键设计决策

ingress-nginx上的网关API -Envoy Gateway实现Gateway API标准，避免将来从不推荐使用的Ingress API迁移
赫尔姆上空的Kustomize --没有模板复杂性的声明性覆盖；更适合GitOps状态存储库
SOPS/外部秘密的密封秘密 --直接提交给Git的加密机密；单个集群的更简单工作流
OpenClaw的状态集 --文件背衬单块PVC复制品；K8s本机安全（网络策略、seccomp、功能）
DaemonSet为Envoy设置hostPort --唯一可行的途径 localhost macOS/KIND上的访问权限（主机无法访问MetalLB VIP）

MCP集成

Claude Code可以通过MCP服务器查询集群状态并管理ArgoCD应用程序：

make setup-mcp

这使得AI辅助操作成为可能：检查pod状态、查看ArgoCD同步状态、读取日志和触发同步——所有这些都是通过Claude Code中的会话命令完成的。MCP默认为只读；写操作需要明确的选择加入。

CI和警卫

清单验证 — make validate 对所有本地基运行kubeconform（也在PR上的CI中运行）
预提交挂钩 --拒绝任何包含明文的提交 kind: Secret 资源(make hooks 安装）
BATS测试套件 --117个测试，涵盖所有清单和脚本(make test)
ArgoCD通知 --同步失败和健康状况下降时触发Webhook
自动备份 --CronJobs用于OpenClaw PVC数据（2AM）和密封密钥导出（3AM）

常见操作

# Cluster operations
make status                            # ArgoCD sync status
make sync                              # Sync all apps
make password                          # ArgoCD admin password
make port-forward                      # ArgoCD UI at localhost:8080
make logs                              # Tail OpenClaw logs
make pods                              # List all pods
make load-image IMAGE=app:dev          # Load image into KIND
make seal FILE=secret.yaml             # Encrypt a secret

# OpenClaw management
make openclaw-onboard                  # First-time setup wizard
make openclaw-health                   # Authenticated health check
make openclaw-channels                 # List channels
make openclaw-cli CMD="channels login" # WhatsApp QR login
make openclaw-shell                    # Shell into the pod

# Validation
make validate                          # Validate manifests
make verify-netpol                     # Test NetworkPolicy enforcement
make check                             # Validate + run all tests

什么不属于这里

应用程序源代码或Dockerfiles --这是一个纯GitOps状态仓库
构建映像的CI管道 --导致无限的GitOps循环
水平缩放配置 --OpenClaw是一个单实例单体
生产云清单 --这是Kinder/KIND上的本地首创

许可证

看许可证.

使用说明

Pincer操作

建筑

快速开始

先决条件

克隆后

独自创立

供应商差异

部署后设置

管理渠道和设备

拆除

生成文件目标

仓库结构

核心不变

关键设计决策

MCP集成

CI和警卫

常见操作

什么不属于这里

许可证

相关 MCP

Harness 平台 MCP 服务器

Argo CD MCP服务器

Kubernetes应用部署服务

Kubernetes GitOps 分析排查 MCP 服务

基础设施自动化MCP服务

Portainer MCP 服务